Theme code

Toolset storefront_code, 16 tools.

ActionsCopy Anchor Link

resolve_update_conflictCopy Anchor Link

The 'Let Klea combine them' choice for a theme update: a code file the merchant and the update both changed gets one combined version. Without content it lists the files and reads one: its text with the merchant's lines, the version before the update and the update's lines between marker lines. With content it checks the whole file you resolved it to by the theme builder's type check and bundle, builds a preview of the theme with it, and keeps it as a proposal. It never changes the update: the merchant looks at the preview on the review page and accepts or turns it down.

Read first: call with theme_id and update_id for the list, then with path (and from/to lines when next is set) for one conflict. Resolve by writing the file as it should be after the update: no marker lines, the merchant's changes kept, the update's changes taken. A proposal with errors is not kept; fix them and send it again. Tell the merchant in plain words what the combined version keeps and takes, and that a preview is on the review page; never show them code or marker lines. Does not publish and does not write to the update.

• Action key: resolve_update.conflict
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "update_id": "019bb77a-30fc-73e0-a0e9-4af113113214"
}

theme_check_runCopy Anchor Link

Build the theme draft and report its type check and build errors.

Build the current draft and wait for it (up to about a minute): status built or failed, the build error and the type check log. This is the authoritative check of a code change; run it before theme_publish.

• Action key: theme_check.run
• Permission: theme.code.write and theme.write
• Approval: Runs without approval.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: safe to repeat with the same input.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe"
}

theme_draft_build_getCopy Anchor Link

Where the theme draft's build stands, with the recent publish builds.

The draft build of a theme (queued, built, failed or skipped; its error and type check log) and the theme's recent publish builds. Every saved file starts a draft build on its own.

• Action key: theme_draft_build.get
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe"
}

theme_email_component_createCopy Anchor Link

Scaffold a new code component for the theme emails in a draft theme.

Create src/emails/components/<Name>.tsx from the email component scaffold in a draft theme; then edit it with theme_file_edit.

• Action key: theme_email_component.create
• Permission: theme.code.write and theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "name": "OrderBanner"
}

theme_file_deleteCopy Anchor Link

Delete files of a draft theme.

Delete files of a draft theme. Each path names the content_hash you read; a file changed since is refused with a conflict. Platform-managed files (.schemas/**) cannot be deleted.

• Action key: theme_file.delete
• Permission: theme.code.write
• Approval: Always waits for a person to approve it.
• Effect: Changes a draft; nothing goes live until it is published.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "files": [
    {
      "path": "src/sections/old.tsx",
      "expected_hash": "ab12"
    }
  ]
}

theme_file_editCopy Anchor Link

Exact text replacements in draft theme files, applied all or nothing.

Replace exact text in files of a draft theme. old_str must occur exactly once (whitespace included) unless replace_all is set; several edits of one file apply in order. All edits apply or none do. expected_hash, when sent, must be the content_hash you read; either way a file changed during the edit is refused with a conflict.

• Action key: theme_file.edit
• Permission: theme.code.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: safe to repeat with the same input.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "edits": [
    {
      "path": "src/sections/hero.tsx",
      "old_str": "Shop now",
      "new_str": "Browse the sale"
    }
  ]
}

theme_file_getCopy Anchor Link

The content and content hash of up to 20 theme files.

Read up to 20 files of a theme draft. Each answer carries content_hash, which every write, edit and delete of that file must send back. from_line and to_line (1-based, inclusive) return part of a file. A long file comes back in part, with next_from_line naming where to read on. Assets answer their stored blob instead of content.

• Action key: theme_file.get
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "paths": [
    {
      "path": "src/sections/hero.tsx"
    }
  ]
}

theme_file_listCopy Anchor Link

The theme's file index: path, kind, size and content hash.

List the files of a theme draft with their content_hash, 80 per page (next_offset reads on). kind is code (src/, og/), manifest (theme.json), asset (assets/) or content (pages, layout, settings, texts, emails, saved JSON). Filter by prefix, kind or a glob such as src/sections//*.tsx.

• Action key: theme_file.list
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "prefix": "src/sections/"
}

theme_file_moveCopy Anchor Link

Rename files of a draft theme.

Rename files of a draft theme. Each move names the content_hash you read; the new path must not exist. Imports of the moved file are not rewritten; search for them with theme_file_search.

• Action key: theme_file.move
• Permission: theme.code.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "moves": [
    {
      "from": "src/sections/old.tsx",
      "to": "src/sections/new.tsx",
      "expected_hash": "ab12"
    }
  ]
}

theme_file_patchCopy Anchor Link

Apply a unified diff to draft theme files, all or nothing.

Apply a unified diff (--- a/path, +++ b/path, @@ hunks; --- /dev/null creates a file) to a draft theme. Each hunk must match the file at its line or at exactly one place. All files apply or none do; a file changed during the patch is refused with a conflict. Delete files with theme_file_delete.

• Action key: theme_file.patch
• Permission: theme.code.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: safe to repeat with the same input.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "patch": "--- a/src/sections/hero.tsx\n+++ b/src/sections/hero.tsx\n@@ -1,1 +1,1 @@\n-Shop now\n+Browse the sale\n"
}

theme_file_searchCopy Anchor Link

Literal or regular expression search across the text files of a theme.

Search the text files of a theme draft. Answers path, line and the line text, at most 200 matches.

• Action key: theme_file.search
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "query": "useCart"
}

theme_file_writeCopy Anchor Link

Create or replace up to 50 whole files in a draft theme.

Write whole files to a draft theme, never the live one. Every file carries expected_hash: the content_hash you read, or null to create a new file. A file changed since you read it is refused with a conflict and nothing is written; read it again and redo the change. A dry run checks paths, imports, page layouts and hashes without writing. For a small change prefer theme_file_edit.

• Action key: theme_file.write
• Permission: theme.code.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: safe to repeat with the same input.
• Dry run: supported, with dry_run set to true.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "files": [
    {
      "path": "src/sections/promo.tsx",
      "content": "export ...",
      "expected_hash": null
    }
  ]
}

theme_preview_captureCopy Anchor Link

Screenshots of a draft page, to check a code change by eye.

Capture a page of the theme draft (desktop by default, or mobile at 390 px). The draft must have finished building; theme_check_run waits for that.

• Action key: theme_preview.capture
• Permission: theme.code.write and theme.write
• Approval: Runs without approval.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: safe to repeat with the same input.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "page_path": "/"
}

theme_preview_createCopy Anchor Link

A preview link of the draft, or of the draft with some files replaced, without saving them.

Without files: a signed preview link of the theme draft once its build is done. With files: a scratch preview of the draft with those files replaced, built on its own and never saved to the draft. Waits up to about a minute for the build.

• Action key: theme_preview.create
• Permission: theme.code.write and theme.write
• Approval: Runs without approval.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: safe to repeat with the same input.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe"
}

theme_revision_diffCopy Anchor Link

What changed between the draft, the live theme and any saved version.

Compare two versions of a theme: by default the draft against what shoppers see now. Answers each changed file (added, modified, removed; lines added and removed), whether code changed, and the flagged patterns a publish approval shows. diff adds unified diffs, paths narrows them.

• Action key: theme_revision.diff
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "diff": true
}

theme_revision_rollbackCopy Anchor Link

Bring an earlier theme version back into the draft.

Restore the draft to a revision from theme_revision_list, replacing every draft theme file, including edits made after it. The live store changes only after theme_publish.

• Action key: theme_revision.rollback
• Permission: theme.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "revision_id": "019bb77a-30fc-73e0-a0e9-4af113113214"
}