Skip to content

Latest commit

 

History

History
124 lines (102 loc) · 6.23 KB

ACTIONS.md

File metadata and controls

124 lines (102 loc) · 6.23 KB

CAIO Actions

An Action is one .js file and that file is the whole artifact, so it can be AirDropped, saved to Files, attached to a message, committed to a gist or pasted into a chat.

File format

// ==CAIO Action==
// @name Uppercase
// @description Uppercases the current text
// @category Text
// @icon textformat
// @color systemBlue
// @needs-app false
// @version 1
// ==/CAIO Action==

module.exports = async function (ctx) {
  const value = ((await Pasteboard.getString()) || "").toUpperCase()
  await ctx.update(value)
  return value
}

The header is optional; a plain .js file also imports (its filename becomes the name). Metadata values are single-line.

Key Meaning
@name Display name (max 120 characters).
@description One-line description shown in the Actions UI (max 500 characters).
@category Folder name; defaults to General.
@icon SF Symbol name; defaults to bolt.
@color Icon background color; defaults to systemBlue.
@needs-app true when the Action needs CAIO's main app (UI/prompts/share).
@version Integer; used to refresh built-ins, defaults to 1.

Context

Actions run in the same Scripting runtime as CAIO, so their context holds only what the runtime cannot provide: writing the result back through CAIO, and reading CAIO's clip history. Everything else — the clipboard, dialogs, previews, storage, the network — is Scripting's own API.

Member Description
ctx.env app, clipboard, editor, keyboard, widget or intent.
ctx.clip The clip the Action was triggered from, or null.
ctx.text The text to start from; "" when there is none.
ctx.update(value) Updates the current clip, inserts into the keyboard/editor, or sets the clipboard.
ctx.clips(collection?) Up to 200 clips from clips, favorite or trash.

The trigger

ctx.clip and ctx.text describe what the user acted on, which is not the same thing as the pasteboard. Run an Action from a clip's long-press menu and ctx.clip is that clip — its id, kind, tag, imagePath, timestamps and text — even though the pasteboard may hold something else entirely. From the clip editor, ctx.text is the unsaved buffer you are looking at, so an Action never has to read stale storage.

module.exports = async function (ctx) {
  // Retag the clip this Action was run on, whatever the pasteboard says.
  const kind = ctx.clip ? ctx.clip.kind : "no clip"
  await ctx.update(`[${kind}] ${ctx.text.toUpperCase()}`)
  return ctx.text.length
}

Both are null / "" where there is no trigger: the Actions tab, the keyboard, a widget or a Shortcut. Write Actions so they fall back to Pasteboard.getString() rather than assuming a clip exists.

Inside the same source, use the native APIs directly instead of a wrapper:

Need Use
Read / set text Pasteboard.getString(), Pasteboard.setString(value)
Keyboard text CustomKeyboard.selectedText, allText, insertText()
Ask the user Dialog.alert, Dialog.confirm, Dialog.prompt, Dialog.actionSheet
Show a result QuickLook.previewText, ShareSheet.present
Remember something Storage.get, Storage.set, Storage.remove

ctx.update(value) is the one writer that routes by host: it replaces the clip that launched the Action, inserts into the keyboard or editor, or sets the pasteboard. To set the clipboard as well, call Pasteboard.setString next to it.

Sharing and installing

  • Export: use Export in the action menu (or drag a card out from All Actions / search) to share the single .caio.js file (AirDrop, Files, Messages, …). Inside a category, long-press drag is reserved for reordering. Cards use Scripting 3.2.2's native drag reordering: a data-backed ForEach with reorderable directly inside a reorderContainer, with move updating the Observable synchronously through setValue. Every card carries its Action id as the key of the view it actually renders. The column count adapts to the available width, and the order is stored locally on the device.
  • Import: Actions tab → Import → choose a .js / .caio.js file. CAIO shows the parsed name/description and a trust warning before installing.
  • Edit: tap a card to edit its code. The context menu separates Action Info (read-only metadata), Edit Info (the file-header comments in a code editor), Edit Code (the executable source) and Edit Full File (header and source together). Pinned state and ordering stay local to the device and are not written into the file.
  • Delete: every Action, including a built-in, can be removed from the bottom of the context menu or the Action Info sheet. Built-in deletions are remembered locally, so the built-in seeder will not recreate them.

Trust

Actions are unsandboxed JavaScript executed in the same script context as CAIO. They can read the clipboard, files and network just like CAIO itself. Only import Actions you trust; the import dialog is the only gate. Settings → “Enable Scripts” is a global kill switch: when off, no Action runs from the app, keyboard, widget or Shortcuts.

Built-ins

Built-ins ship as flat files in CAIO/actions/ and are rewritten when CAIO updates them. They are normal Actions; export or copy one as a starting point.