@graph8/sdk 0.357.0 → 0.358.0

package/dist/types/version.d.ts

@@ -5,6 +5,6 @@
  * both together (the version-parity gate already pins package.json, the
  * lockfile and the CHANGELOG to each other).
  */
-export declare const SDK_VERSION = "0.357.0";
+export declare const SDK_VERSION = "0.358.0";
 /** Value of the `X-G8-Client` header every SDK request carries (I-13). */
-export declare const SDK_CLIENT_ID = "js-sdk/0.357.0";
+export declare const SDK_CLIENT_ID = "js-sdk/0.358.0";

package/docs/api/enrichment.d.ts

@@ -355,6 +355,8 @@ export interface EnrichmentOperations {
     query?: {
       /** Remove the configuration permanently instead of deactivating it. The values it already wrote are kept either way. */
       hard_delete?: boolean;
+      /** Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. */
+      scope?: string | null;
     };
     headers?: {
       "X-Target-Org-Id"?: string | null;
@@ -376,6 +378,8 @@ export interface EnrichmentOperations {
     query?: {
       /** Remove the configuration permanently instead of deactivating it. The values it already wrote are kept either way. */
       hard_delete?: boolean;
+      /** Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. */
+      scope?: string | null;
     };
     headers?: {
       "X-Target-Org-Id"?: string | null;
@@ -414,6 +418,8 @@ export interface EnrichmentOperations {
     query?: {
       /** Remove the configuration permanently instead of deactivating it. The values it already wrote are kept either way. */
       hard_delete?: boolean;
+      /** Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. */
+      scope?: string | null;
     };
     headers?: {
       "X-Target-Org-Id"?: string | null;
@@ -1566,6 +1572,10 @@ export interface EnrichmentOperations {
       /** AI group id. */
       group_id: string;
     };
+    query?: {
+      /** Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. */
+      scope?: string | null;
+    };
     headers?: {
       "X-Target-Org-Id"?: string | null;
     };
@@ -1829,6 +1839,10 @@ export interface EnrichmentOperations {
       /** The AI group id. */
       group_id: string;
     };
+    query?: {
+      /** Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. */
+      scope?: string | null;
+    };
     headers?: {
       "X-Target-Org-Id"?: string | null;
     };
@@ -1883,6 +1897,10 @@ export interface EnrichmentOperations {
       /** Enrichment configuration id (UUID). */
       config_id: string;
     };
+    query?: {
+      /** Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. */
+      scope?: string | null;
+    };
     headers?: {
       "X-Target-Org-Id"?: string | null;
     };

package/docs/api/enrichment.md

@@ -802,7 +802,9 @@ const result = await g8.api.enrichment.createRoutingRule({ body: { name: "Exampl
 Drop ONE column from an AI group. The group and its other columns stay.
 
 Free. `columns` is plural here where the app writes `column`, so the path
-reads the same way as every other collection in this contract.
+reads the same way as every other collection in this contract. A column of
+a qualification group shared by every list answers 409 unless `scope=org`
+(admin keys only).
 
 **Input**
 
@@ -811,6 +813,7 @@ reads the same way as every other collection in this contract.
 | `path.group_id` | `string` | yes | AI group id. |
 | `path.column_id` | `string` | yes | The single column to drop. |
 | `query.hard_delete` | `boolean` | no | Remove the configuration permanently instead of deactivating it. The values it already wrote are kept either way. default `false` |
+| `query.scope` | `string \| null` | no | Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. |
 
 **Returns** `ApiResponse_EnrichmentPayload_`: the envelope `{ data: EnrichmentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -838,12 +841,16 @@ const result = await g8.api.enrichment.deleteAiConfigByColumn({ path: { group_id
 
 Remove an AI group and every column it owns. Free.
 
+A qualification group shared by every list answers 409 unless `scope=org`
+(admin keys only).
+
 **Input**
 
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `path.group_id` | `string` | yes | AI group id. |
 | `query.hard_delete` | `boolean` | no | Remove the configuration permanently instead of deactivating it. The values it already wrote are kept either way. default `false` |
+| `query.scope` | `string \| null` | no | Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. |
 
 **Returns** `ApiResponse_EnrichmentPayload_`: the envelope `{ data: EnrichmentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -903,12 +910,16 @@ const result = await g8.api.enrichment.deleteAutoEnrichmentConfig({ path: { conf
 
 Remove an enrichment configuration. Free.
 
+A qualification configuration shared by every list answers 409 unless
+`scope=org` (admin keys only).
+
 **Input**
 
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `path.config_id` | `string` | yes | Enrichment configuration id (UUID). |
 | `query.hard_delete` | `boolean` | no | Remove the configuration permanently instead of deactivating it. The values it already wrote are kept either way. default `false` |
+| `query.scope` | `string \| null` | no | Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. |
 
 **Returns** `ApiResponse_EnrichmentPayload_`: the envelope `{ data: EnrichmentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -3505,7 +3516,8 @@ const result = await g8.api.enrichment.previewRoutingRule({ body: { source_list_
 Rename the column an AI group writes into. Free.
 
 Display name only - the underlying column id does not move, so formulas and
-mappings that reference it keep working.
+mappings that reference it keep working. A qualification group shared by
+every list answers 409 unless `scope=org` (admin keys only).
 
 **Input**
 
@@ -3513,6 +3525,7 @@ mappings that reference it keep working.
 |---|---|---|---|
 | `path.group_id` | `string` | yes | AI group id. |
 | `body` | `RenameAIColumnRequest` | yes | Request body; fields below. |
+| `query.scope` | `string \| null` | no | Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. |
 
 Body fields (`RenameAIColumnRequest`):
 
@@ -4006,6 +4019,10 @@ EVERY list in the organisation, not just `config.list_id`. That is the
 wider blast radius of the two and it is what you get by omission, so set it
 deliberately.
 
+A `config.group_id` naming a qualification group shared by every list (the
+ICP and Persona qualification groups) answers 409 with code
+`shared_qualification_group`: those groups cannot gain columns here.
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -4308,7 +4325,8 @@ const result = await g8.api.enrichment.unassignConfigFromList({
 Edit an AI group in place. Free: editing runs nothing.
 
 Output columns that already exist keep their data; the run condition is
-validated before anything is saved.
+validated before anything is saved. A qualification group shared by every
+list answers 409 unless `scope=org` (admin keys only).
 
 **Input**
 
@@ -4316,6 +4334,7 @@ validated before anything is saved.
 |---|---|---|---|
 | `path.group_id` | `string` | yes | The AI group id. |
 | `body` | `UpdateAIConfigRequest` | yes | Request body; fields below. |
+| `query.scope` | `string \| null` | no | Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. |
 
 Body fields (`UpdateAIConfigRequest`):
 
@@ -4452,7 +4471,8 @@ Change fields on an enrichment configuration. Free.
 Whatever keys are sent are written - the app takes a free-form body here
 and this forwards it unchanged rather than narrowing what the browser can
 already do. `updated_by` is stamped from the calling key and cannot be
-supplied.
+supplied. A qualification configuration shared by every list answers 409
+unless `scope=org` (admin keys only).
 
 **Input**
 
@@ -4460,6 +4480,7 @@ supplied.
 |---|---|---|---|
 | `path.config_id` | `string` | yes | Enrichment configuration id (UUID). |
 | `body` | `EnrichmentConfigUpdateRequest` | yes | Request body; fields below. |
+| `query.scope` | `string \| null` | no | Set to `org` to change or delete a qualification group shared by every list (the ICP and Persona qualification groups). Admin keys only. Without it such a call answers 409 with code `shared_qualification_group`. |
 
 Body fields (`EnrichmentConfigUpdateRequest`):
 

package/docs/api/revenueLifecycle.d.ts

@@ -153,7 +153,9 @@ export interface LifecycleRecordItem {
 }
 
 export interface LifecycleStageMoveRequest {
-  /** Company moves only: run every check the move runs (company exists, stage known, Customers/Churned guards) and return the would-be transition without writing anything. Ignored for contact moves. */
+  /** Confirm a move to Customers of a company with no subscription (or a contact with no company or whose company has none). Without it such a move is refused with 409 and detail.code 'customers_without_subscription'. */
+  confirm_without_subscription?: boolean;
+  /** Run every check the move runs (record exists, stage known, Customers/Churned guards, the no-subscription confirmation) and return the would-be transition without writing anything. */
   dry_run?: boolean;
   /** Destination lifecycle slug, e.g. 'suspects', 'leads', 'trials', 'customers', 'churned'. Case and surrounding whitespace are ignored, and a stage's display name is accepted too. */
   target_slug: string;

package/docs/api/revenueLifecycle.md

@@ -191,6 +191,10 @@ with a 400 unless the company is or was a customer. `target_slug` ignores
 case and surrounding whitespace. `dry_run: true` runs every check and
 returns the would-be transition without writing anything.
 
+A move to `customers` of a company with no subscription at all is a 409
+(`detail.code` 'customers_without_subscription', `detail.message` names the
+company) unless `confirm_without_subscription: true` is sent (R3-30).
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -203,7 +207,8 @@ Body fields (`LifecycleStageMoveRequest`):
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `body.target_slug` | `string` | yes | Destination lifecycle slug, e.g. 'suspects', 'leads', 'trials', 'customers', 'churned'. Case and surrounding whitespace are ignored, and a stage's display name is accepted too. |
-| `body.dry_run` | `boolean` | no | Company moves only: run every check the move runs (company exists, stage known, Customers/Churned guards) and return the would-be transition without writing anything. Ignored for contact moves. default `false` |
+| `body.confirm_without_subscription` | `boolean` | no | Confirm a move to Customers of a company with no subscription (or a contact with no company or whose company has none). Without it such a move is refused with 409 and detail.code 'customers_without_subscription'. default `false` |
+| `body.dry_run` | `boolean` | no | Run every check the move runs (record exists, stage known, Customers/Churned guards, the no-subscription confirmation) and return the would-be transition without writing anything. default `false` |
 
 **Returns** `ApiResponse_LifecycleStageMoveResponse_`: the envelope `{ data: LifecycleStageMoveResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -247,6 +252,10 @@ yet, which is common for Suspects-stage contacts), and records the same
 audit trail the in-app Move-Stage dialog's contact mode does. Returns no
 contact PII (see the module docstring) — only the status transition.
 
+A move to `customers` of a contact with no company, or whose company has no
+subscription, is a 409 (`detail.code` 'customers_without_subscription')
+unless `confirm_without_subscription: true` is sent (R3-31).
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -259,7 +268,8 @@ Body fields (`LifecycleStageMoveRequest`):
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `body.target_slug` | `string` | yes | Destination lifecycle slug, e.g. 'suspects', 'leads', 'trials', 'customers', 'churned'. Case and surrounding whitespace are ignored, and a stage's display name is accepted too. |
-| `body.dry_run` | `boolean` | no | Company moves only: run every check the move runs (company exists, stage known, Customers/Churned guards) and return the would-be transition without writing anything. Ignored for contact moves. default `false` |
+| `body.confirm_without_subscription` | `boolean` | no | Confirm a move to Customers of a company with no subscription (or a contact with no company or whose company has none). Without it such a move is refused with 409 and detail.code 'customers_without_subscription'. default `false` |
+| `body.dry_run` | `boolean` | no | Run every check the move runs (record exists, stage known, Customers/Churned guards, the no-subscription confirmation) and return the would-be transition without writing anything. default `false` |
 
 **Returns** `ApiResponse_LifecycleStageMoveResponse_`: the envelope `{ data: LifecycleStageMoveResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 

package/docs/api/seo.d.ts

@@ -859,7 +859,7 @@ export interface SeoResearchKeywordsResponse {
  * refused with a 422 if it carries a scheme or a path.
  */
 export interface SeoSaveTrackedKeywordsRequest {
-  cadence?: "daily" | "weekly";
+  cadence?: "daily" | "weekly" | "manual";
   domain: string;
   keywords: Array<SeoTrackKeywordItem>;
   language_code?: string;

package/docs/api/seo.md

@@ -1025,7 +1025,7 @@ Body fields (`SeoSaveTrackedKeywordsRequest`):
 |---|---|---|---|
 | `body.domain` | `string` | yes | min length 3, max length 255 |
 | `body.keywords` | `Array<SeoTrackKeywordItem>` | yes | min items 1, max items 100 |
-| `body.cadence` | `"daily" \| "weekly"` | no | default `"daily"` |
+| `body.cadence` | `"daily" \| "weekly" \| "manual"` | no | default `"daily"` |
 | `body.language_code` | `string` | no | default `"en"`, max length 10 |
 | `body.location_code` | `integer` | no | default `2840` |
 

package/docs/api/workflows.md

@@ -193,6 +193,14 @@ Send an `Idempotency-Key` header as well for the app-wide guard.
 Every execution in the batch is scoped to the caller's org before it is
 touched; ids belonging to another tenant are simply not found.
 
+A restart runs each workflow as it is NOW. When one has record steps or a
+record trigger, the key needs the object scopes they exercise (403
+``missing_scopes`` refuses the whole batch, nothing restarts), and only the
+workflow's owner or a graph8 admin may restart it: for any other member that
+item is reported in ``failed`` with ``owner_or_admin_required`` while the
+rest of the batch goes ahead. When graph8 cannot confirm who is an admin,
+that item is refused, never guessed, and also reported in ``failed``.
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -319,6 +327,13 @@ const result = await g8.api.workflows.createWorkbench({ body: {} });
 Create a new workflow. Pins ``org_id`` and ``runtime_type='workflow'``
 server-side - the body cannot override either.
 
+The workflow's OWNER is the authenticated caller, never a body field: a
+body ``created_by`` is dropped (see ``voice_owner_headers``). Record steps
+and record triggers run with the owner's record access, so the key must hold
+the object scopes they exercise (403 ``missing_scopes``). A node or trigger
+config that carries the same key in snake_case and camelCase with values
+that disagree is refused (422 ``conflicting_node_keys``): keep one spelling.
+
 Translates the public ``config`` field to voice's internal
 ``skill_config`` before forwarding (see module docstring).
 
@@ -573,6 +588,14 @@ const result = await g8.api.workflows.diffSkillVersions({ path: { action_id: "id
 
 Trigger a workflow run. Returns ``execution_id`` for polling.
 
+A workflow with record steps or a record trigger runs them with its OWNER's
+record access, and this run's input feeds them: the key must hold the object
+scopes they exercise (403 ``missing_scopes``) and its member must own the
+workflow or administer the org (403 ``owner_or_admin_required``, from the
+workflow service, which receives the member as the verified identity). The
+saved workflow is read before the run so that check is never skipped: when
+it cannot be read, the answer is ``502`` and nothing runs.
+
 Pins ``org_id`` server-side; the caller cannot override which org's
 execution row is created. ``triggered_by`` defaults to the caller's
 user id when not supplied.
@@ -1908,6 +1931,14 @@ a paused run instead, use `POST /workflows/executions/{id}/resume`.
 The org is forwarded and voice scopes the lookup by it, so one tenant
 cannot restart another's run.
 
+A restart runs the workflow as it is NOW, with the original or new input.
+When it has record steps or a record trigger, the key needs the object
+scopes they exercise (403 ``missing_scopes``), and only the workflow's
+owner or a graph8 admin may restart it, with reused or new input (403
+``owner_or_admin_required``). When graph8 cannot confirm who is an admin the
+restart is refused, never guessed: the workflow service answers 503, which
+reaches the caller as ``502`` like its other upstream failures; retry later.
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -1941,7 +1972,14 @@ const result = await g8.api.workflows.restartExecution({ path: { execution_id: "
 
 SPENDS NOTHING. Publishes the old snapshot as a NEW version, live for the
 next run - agents and workflows using the skill pick it up. Append-only, so
-the restore can itself be rolled back. Routine-managed skills refuse (403).
+the restore can itself be rolled back. Routine-managed skills refuse (403). A
+restored graph with record steps or a record trigger needs the same object
+scopes as a create or an update (403 ``missing_scopes``), a restored graph
+whose snake_case and camelCase node keys disagree is refused (422
+``conflicting_node_keys``), and a restore that changes such a workflow's
+graph is refused (403 ``owner_or_admin_required``) unless the key's member
+owns the workflow or administers the org. The version's graph is read first
+to run those checks: 404 when it cannot be found (unknown skill or version).
 
 **Input**
 
@@ -2250,7 +2288,13 @@ const result = await g8.api.workflows.updateSkillTestCase({ path: { action_id: "
 - ★ Hand-written: [`g8.workflows.update()`](../sdk-clients.md#g8-workflows-update)
 
 Update a workflow. The voice update endpoint takes ``org_id`` as a
-query param and the partial body in JSON, so we forward both.
+query param and the partial body in JSON, so we forward both. A graph with
+record steps or a record trigger needs the object scopes they exercise
+(403 ``missing_scopes``), like create, and a node or trigger config whose
+snake_case and camelCase keys disagree is refused (422
+``conflicting_node_keys``). On a workflow with record steps or a record
+trigger, only its owner or a graph8 admin may change what it runs (403
+``owner_or_admin_required``); its name and description stay editable.
 
 Translates the public ``config`` field to voice's internal
 ``skill_config`` before forwarding (see module docstring).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graph8/sdk",
-  "version": "0.357.0",
+  "version": "0.358.0",
   "description": "graph8 SDK - CRM, enrichment, sequences, campaigns, and tracking for B2B",
   "license": "MIT",
   "author": "graph8 <support@graph8.com> (https://graph8.com)",