@inboxychat/sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,29 @@
-# @inboxychat/sdk — read-only client for the Inboxy public API v1
+# @inboxychat/sdk — scoped Inboxy client
 
-Used by `@inboxychat/mcp` and `@inboxychat/cli`. Local package, not published.
+Published on npm as [`@inboxychat/sdk`](https://www.npmjs.com/package/@inboxychat/sdk); also used by
+`@inboxychat/mcp` and `@inboxychat/cli`. Full guide (English and Arabic):
+https://inboxy.chat/developers/sdk
+
+```bash
+npm i @inboxychat/sdk          # Node.js 20.3+, ESM only
+```
+
+```ts
+import { InboxyClient, collectPages } from '@inboxychat/sdk';
+
+const inboxy = new InboxyClient({ apiKey: process.env.INBOXY_API_KEY! });
+const { data: me } = await inboxy.getCompany();
+const orders = await inboxy.listOrders({ status: 'pending', limit: 5 });
+const { items } = await collectPages((q) => inboxy.listContacts(q), { limit: 100 }, 20);
+```
+
+Create the key in the Inboxy dashboard as a company admin (Developers → API,
+`/developer-center/api`), with only the scopes you need. Keep it on the server; never ship
+it to a browser.
 
 - `InboxyClient`: one GET method per route in `PUBLIC_ROUTES` (the same list as
   `PUBLIC_API_V1_ROUTES` in `apps/api/src/modules/api-public/api-public.contract.ts`).
-  No write methods, no company parameter, HTTPS only (http for localhost),
+  No company parameter, HTTPS only (http for localhost),
   redirects refused, per-request timeout and `AbortSignal`.
 - `InboxyError`: `kind` (`auth`, `forbidden`, `not_found`, `rate_limited`,
   `invalid_request`, `server`, `timeout`, `cancelled`, `network`,
@@ -21,3 +40,73 @@ against them, so a change on either side fails a test.
 ```bash
 pnpm --filter @inboxychat/sdk test
 ```
+
+## Audited operation adapters
+
+This source version adds 80 operations through `describeOperations()`,
+`prepareOperation(id, input, idempotencyKey)` and `client.executeOperation(...)`.
+The eleven public read methods remain compatible. The operation catalog covers
+contact create/update; task list/get/create/update/assign/complete; ticket
+list/get/create/update/assign/close/internal-note; AI employee list/get/draft,
+configuration/test/readiness/explicit publication; campaign list/get/draft.
+
+```ts
+import { prepareOperation } from '@inboxychat/sdk';
+const input = { body: { title: 'Call customer tomorrow' } };
+const idempotencyKey = crypto.randomUUID();
+const preview = prepareOperation('tasks.create', input, idempotencyKey);
+// Display preview (including warnings) and obtain the user's explicit approval.
+const result = await inboxy.executeOperation('tasks.create', input, {
+  idempotencyKey, confirmation: preview.confirmation,
+});
+```
+
+Every mutation requires its exact normalized preview hash and an idempotency key.
+The hash binds the operation, fields and key; it is a consistency guard, not proof
+of human consent. The caller must collect approval. A changed request requires a
+new preview. Retain the key when recovering an uncertain outcome; never create a
+new key merely because a request timed out. There are no automatic retries.
+Server scope, tenant, current role, plan and feature gates remain authoritative.
+AI tests may use credits; publication enables live replies and may replace the
+employee on selected channels. Campaign creation omits all scheduling fields and
+creates a draft. Ticket notes are forced internal. No arbitrary URL/body proxy, company override, entity deletion, billing or admin operation is exposed. One text send is available only through explicit recipient/channel/content approval.
+
+`API_ROUTE_INVENTORY` is generated discovery metadata for 553 API-token routes;
+it does not make those routes executable. Actual full UI parity is **not** claimed.
+Remaining adapter classes include media/template/bulk sends, channel OAuth, order
+cancellation/refunds, advanced commerce/catalog operations, flows/automation, URL/file
+knowledge ingestion, expanded analytics, webhook/token management, billing and admin.
+They need separate schemas, consent/effect review and tests.
+
+After intentional server/catalog changes, run
+`node packages/inboxy-sdk/scripts/generate-operations.mjs` from the repository root.
+The contract test checks method/path/scope and generated-file drift. This is source
+implementation, not evidence that the npm release or hosted service is deployed.
+
+
+### Expanded operation coverage
+
+The source catalog now has 80 operations (553 discovery routes). Added inbox
+assignment/status/labels/internal notes; separate one-message text sending;
+reviewed AI text knowledge and channel assignments; manual orders, state/payment/
+fulfillment records; product/category creation and updates. Inspect the catalog
+for exact schemas. Media/templates/bulk sends, scheduling, order cancellation/
+refunds, URL/file knowledge ingestion and complete automation coverage remain out
+of scope. Orders may trigger configured automation; payment-record changes do not
+charge a payment provider.
+
+For a send, preview `inbox.message.send` with `conversationId`, `target` containing
+`contactId`, `channelId`, `channelType` (uppercase enum), and `body.content`.
+Inspect the conversation first and approve the exact recipient, channel and full
+text. CLI uses `messages send --input <same-json> --idempotency-key <same-key>
+--confirm <hash>`; MCP uses the separate `message_send` tool with identical input,
+idempotencyKey and confirmation. Generic operation execution in CLI/MCP refuses
+sends. The SDK dispatch includes a confirmed-target header, validated against the
+current tenant conversation before send; a mismatch requires a new inspection and
+approval. Stable clientMessageId supplements the existing idempotency middleware.
+
+The lifecycle slice adds contact status/stage/assignment/internal notes, tag management and bounded flat custom-field replacement. It adds automation graph/run inspection, inactive draft creation and pause, plus campaign audience estimation, pause and cancel. Tag changes may trigger configured automations. Automation graph editing/publish remain unavailable; a preview estimate does not authorize scheduling.
+
+Workflow activation: first execute `automations.activation.preview`, show the entire returned preview, then pass it unchanged as `body.approval` to `automations.activate` with an exact confirmation and idempotency key. The server rechecks tenant, published version/hash, complete preview and workflow revision in a transaction. MCP uses `lifecycle_activate`; CLI uses `lifecycle activate <operation>`. The generic operation runner refuses activate effects, including AI publish/channel changes. `automations.simulate` uses existing dry services and skips external side effects.
+
+Campaign delivery uses `campaigns.approval` to resolve a complete snapshot (audience, sender, template/content, limits and exact time). Pass that unchanged in `body.approval` to `campaigns.send`, `campaigns.resume` or `campaigns.schedule`, preview locally, then obtain explicit approval. MCP requires `campaign_send` or `campaign_schedule`; CLI requires `campaigns send <operation>` or `campaigns schedule`. The server freezes approval and checks it again before delivery. These actions can send real customer messages and consume budget. Keep the same idempotency key for recovery. Version 0.2.0 is prepared locally; publication and API deployment are separate release steps.