From 3654118ad2615bd0f6548131fc1c5ec0e05a5b56 Mon Sep 17 00:00:00 2001 From: Gianluca Esposito Date: Fri, 4 Sep 2026 12:28:36 +0200 Subject: [PATCH] chore: move the examples to @gathertown/webhook-object-sdk 0.3.0 Bumps the SDK and types pins from ^0.1.1 to ^0.3.0 so the examples pick up the `variant` base capability, the `signal` preset, and the `colors` field on `pong`. Documents all three in the Smart Objects reference and drops the `sync-objects` skill, which described regenerating types into the `packages/client` package that #15 removed. --- .claude/skills/sync-objects/SKILL.md | 27 ------------------ docs/reference.md | 34 ++++++++++++++++------ packages/claude-status/package.json | 4 +-- packages/gh-prs-inbox/package.json | 2 +- packages/low-battery-switch/package.json | 2 +- packages/now-playing-inbox/package.json | 2 +- pnpm-lock.yaml | 36 ++++++++++++------------ 7 files changed, 49 insertions(+), 58 deletions(-) delete mode 100644 .claude/skills/sync-objects/SKILL.md diff --git a/.claude/skills/sync-objects/SKILL.md b/.claude/skills/sync-objects/SKILL.md deleted file mode 100644 index bc6563e..0000000 --- a/.claude/skills/sync-objects/SKILL.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: sync-objects -description: Regenerate the generated domain types in packages/client/src/objects from a new gather-game-logic commit and bump the VERSION const in lockstep. Use when updating webhook object/event/capability types or pointing at a newer gather-game-logic revision. ---- - -# Sync generated object types - -`packages/client/src/objects/{capabilities,events,presets,responses}.ts` are generated from `gather-game-logic`. `src/objects/index.ts` records the source commit in a `VERSION` const: - -```ts -/** The `gather-game-logic` commit these type definitions were generated from. */ -export const VERSION = "83b42349949bf0e0d9c2497d8bbbb016840b2995" as const; -``` - -## Rule - -`VERSION` and the type files must always come from the **same commit**. A mismatch is the bug this skill exists to prevent. - -## Steps - -1. Get the target `gather-game-logic` commit SHA (ask if not given; default to its current `main` head). -2. Regenerate the four type files from that commit. (Use whatever generator the source repo provides — there is no generator checked into this monorepo; if the user hasn't specified one, ask how the types were last produced rather than hand-editing.) -3. Update `VERSION` in `src/objects/index.ts` to the exact same SHA. -4. If the type surface changed, re-check the public export wiring — see [add-public-export](../add-public-export/SKILL.md). -5. Run [verify](../verify/SKILL.md); fix any spec drift the new types cause. - -Don't hand-edit the generated files to "fix" a type — fix it upstream and regenerate, or the next sync silently reverts it. diff --git a/docs/reference.md b/docs/reference.md index e933209..d11fc17 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -25,14 +25,15 @@ The SDK handles the wire protocol — HMAC signing, retries, the 4 KB body cap, ## Presets -An object's **preset** is chosen when you place it in Gather and fixes which **capabilities** — and therefore which events — it accepts. Every preset includes the base `info` capability, and every object also answers `webhook.ping`. +An object's **preset** is chosen when you place it in Gather and fixes which **capabilities** — and therefore which events — it accepts. Every preset includes the base `info` and `variant` capabilities, and every object also answers `webhook.ping`. -| Preset | Capabilities | Good for | -| --------- | ----------------------- | ------------------------------------------------------------ | -| `counter` | info, counter | a single number — build depth, active users, a score | -| `switch` | info, switch | a binary state — a lamp, a door, "on air" | -| `status` | info, status, activity | an indicator with a state + a feed — an agent's status light | -| `inbox` | info, activity, counter | a feed with a count badge — PRs to review, incidents, tasks | +| Preset | Capabilities | Good for | +| --------- | -------------------------------- | --------------------------------------------------------------- | +| `counter` | info, variant, counter | a single number — build depth, active users, a score | +| `switch` | info, variant, switch | a binary state — a lamp, a door, "on air" | +| `status` | info, variant, status, activity | an indicator with five states + a feed — an agent's status light | +| `signal` | info, variant, signal, activity | an indicator with three states + a feed — quiet / active / alert | +| `inbox` | info, variant, activity, counter | a feed with a count badge — PRs to review, incidents, tasks | ## Events @@ -46,6 +47,14 @@ The object's user-facing identity. | ---------- | --------------------------------------------------- | | `info.set` | `name?` string ≤ 120 · `description?` string ≤ 2000 | +### `variant` — every object + +The object's color. Setting it switches the object to the matching color variant of its catalog item, the same change as picking a color in the editor, and it persists. Colors differ per object: `webhook.ping` returns the ones this object ships as `colors`. A color outside that list is ignored rather than rejected. There is no reset; send the original color again to revert. + +| Event | Args | +| ------------- | ------------------------------------------------------- | +| `variant.set` | `color` string, one of the object's `colors` _(required)_ | + ### `counter` A single non-negative integer, or unset (`null`). @@ -75,6 +84,15 @@ A single named indicator state. | `status.set` | `state` one of `off` · `on` · `question` · `alert` · `working` _(required)_ | | `status.reset` | — · returns to `off` | +### `signal` + +A three-way signal light. Its states are a subset of `status`'s, so art tagged `off` / `on` / `alert` renders for either; pick `signal` when quiet / active / needs-attention is the whole story. + +| Event | Args | +| -------------- | --------------------------------------------------- | +| `signal.set` | `state` one of `off` · `on` · `alert` _(required)_ | +| `signal.reset` | — · returns to `off` | + ### `activity` A bounded, newest-wins feed rendered in the object's details popover. Each entry has a stable `id`: re-sending the same `id` updates that entry, and stale or out-of-order redeliveries are ignored (ordering uses the signed send time). The feed is capped to the newest entries, and the popover derives a favicon from the entry `url`'s host. @@ -87,7 +105,7 @@ A bounded, newest-wins feed rendered in the object's details popover. Each entry ### `webhook.ping` — every object -Reserved health check. Signed like any event but takes no data; returns the object's current preset and capability state (`pong`). Use it to verify the secret and discover which capabilities the object accepts. +Reserved health check. Signed like any event but takes no data; returns the object's current preset, its capability state, and the `colors` its art ships (`pong`). Use it to verify the secret, discover which capabilities the object accepts, and learn which values `variant.set` will resolve. ## The examples diff --git a/packages/claude-status/package.json b/packages/claude-status/package.json index 65c64e4..6b9f5d5 100644 --- a/packages/claude-status/package.json +++ b/packages/claude-status/package.json @@ -23,10 +23,10 @@ } ], "dependencies": { - "@gathertown/webhook-object-sdk": "^0.1.1" + "@gathertown/webhook-object-sdk": "^0.3.0" }, "devDependencies": { - "@gathertown/webhook-object-types": "^0.1.1", + "@gathertown/webhook-object-types": "^0.3.0", "@webhook-objects/z-build-config": "workspace:*" } } diff --git a/packages/gh-prs-inbox/package.json b/packages/gh-prs-inbox/package.json index 58adb93..f4eb755 100644 --- a/packages/gh-prs-inbox/package.json +++ b/packages/gh-prs-inbox/package.json @@ -19,6 +19,6 @@ } ], "dependencies": { - "@gathertown/webhook-object-sdk": "^0.1.1" + "@gathertown/webhook-object-sdk": "^0.3.0" } } diff --git a/packages/low-battery-switch/package.json b/packages/low-battery-switch/package.json index 6cc9fd6..2f30d7c 100644 --- a/packages/low-battery-switch/package.json +++ b/packages/low-battery-switch/package.json @@ -19,6 +19,6 @@ } ], "dependencies": { - "@gathertown/webhook-object-sdk": "^0.1.1" + "@gathertown/webhook-object-sdk": "^0.3.0" } } diff --git a/packages/now-playing-inbox/package.json b/packages/now-playing-inbox/package.json index 0d46c0c..169c606 100644 --- a/packages/now-playing-inbox/package.json +++ b/packages/now-playing-inbox/package.json @@ -22,6 +22,6 @@ } ], "dependencies": { - "@gathertown/webhook-object-sdk": "^0.1.1" + "@gathertown/webhook-object-sdk": "^0.3.0" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0451e90..803dd6a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -36,12 +36,12 @@ importers: packages/claude-status: dependencies: '@gathertown/webhook-object-sdk': - specifier: ^0.1.1 - version: 0.1.1 + specifier: ^0.3.0 + version: 0.3.0 devDependencies: '@gathertown/webhook-object-types': - specifier: ^0.1.1 - version: 0.1.1 + specifier: ^0.3.0 + version: 0.3.0 '@webhook-objects/z-build-config': specifier: workspace:* version: link:../z-build-config @@ -49,20 +49,20 @@ importers: packages/gh-prs-inbox: dependencies: '@gathertown/webhook-object-sdk': - specifier: ^0.1.1 - version: 0.1.1 + specifier: ^0.3.0 + version: 0.3.0 packages/low-battery-switch: dependencies: '@gathertown/webhook-object-sdk': - specifier: ^0.1.1 - version: 0.1.1 + specifier: ^0.3.0 + version: 0.3.0 packages/now-playing-inbox: dependencies: '@gathertown/webhook-object-sdk': - specifier: ^0.1.1 - version: 0.1.1 + specifier: ^0.3.0 + version: 0.3.0 packages/z-build-config: {} @@ -314,12 +314,12 @@ packages: cpu: [x64] os: [win32] - '@gathertown/webhook-object-sdk@0.1.1': - resolution: {integrity: sha512-lKy/S8bA1Ux0+RAlQAEn6K5FCmQrdIF3QwE+31OBPUAsOqdFeUbb9xvrSuyus2+nqL/JOIQU3QFcFXuHxDLoiA==} - engines: {node: '>=18'} + '@gathertown/webhook-object-sdk@0.3.0': + resolution: {integrity: sha512-S01RnQ8W29bjGkzqPtLLZqgKyJDr2EgQhLOGHHcbbVuGKQZNnMwBHQS+Bvd5aqb46KuIZXFei46keVf2hG5cyA==} + engines: {node: '>=24'} - '@gathertown/webhook-object-types@0.1.1': - resolution: {integrity: sha512-jJBooZyBW/lRHwY7njRWjr2y1oaZEWBW719sZElV3ipv2a0EymR/AZZtW8jJrkVWP+OhuVSb7EUHVEE0dMb9mA==} + '@gathertown/webhook-object-types@0.3.0': + resolution: {integrity: sha512-13JDgGpvO6ReLJ47kMRLKYePVt50ULadWqDcqg/s9ufL9x3K+5NtKWTHZNQj/eEB9XwuGWUxNWHyvTVwg1HDOg==} '@jridgewell/resolve-uri@3.1.2': resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==} @@ -1072,12 +1072,12 @@ snapshots: '@esbuild/win32-x64@0.28.1': optional: true - '@gathertown/webhook-object-sdk@0.1.1': + '@gathertown/webhook-object-sdk@0.3.0': dependencies: - '@gathertown/webhook-object-types': 0.1.1 + '@gathertown/webhook-object-types': 0.3.0 standardwebhooks: 1.0.0 - '@gathertown/webhook-object-types@0.1.1': {} + '@gathertown/webhook-object-types@0.3.0': {} '@jridgewell/resolve-uri@3.1.2': {}