@ziggs-ai/api-client 0.37.10 → 0.37.12

package/dist/capabilities/context.js

@@ -1,4 +1,5 @@
 import { isContextAccessRequest } from '../shared/contextAccessRequest.js';
+import { looksLikeHandle, parseRef } from '../handles.js';
 import { presentResourceActions } from './resourceActions.js';
 import { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, parseVia, viaHint, } from '../http/ContextReadClient.js';
 import { ContextOpenClient } from '../http/ContextOpenClient.js';
@@ -255,31 +256,24 @@ export const contextDelegateCapability = {
         };
     },
 };
-const OPEN_ID_PARAMS = {
-    artifactId: {
+const OPEN_REF_PARAMS = {
+    ref: {
         type: 'string',
-        description: 'Artifact id from a prior response. Pass exactly one id field.',
-    },
-    chatId: {
-        type: 'string',
-        description: 'Chat id from a prior response. Pass exactly one id field.',
-    },
-    taskId: {
-        type: 'string',
-        description: 'Task id from a prior response. Pass exactly one id field.',
-    },
-    agreementId: {
-        type: 'string',
-        description: 'Agreement id from a prior response. Pass exactly one id field.',
+        required: true,
+        description: 'What to open: a handle such as T7K2QXD (T task, A agreement, C chat, F artifact) in any case, a Ziggs web URL holding one, or an id from a prior response.',
     },
 };
 function openBodyFromArgs(args) {
-    const body = {};
-    for (const key of ['artifactId', 'chatId', 'taskId', 'agreementId']) {
-        const value = args[key];
-        if (typeof value === 'string' && value.trim())
-            body[key] = value.trim();
-    }
+    // A mistyped handle is refused here, before any call: its check letter
+    // fails. Any other id goes to the server, which knows older shapes.
+    const raw = typeof args.ref === 'string' ? args.ref.trim() : '';
+    const invalid = (message) => Object.assign(new Error(message), { code: 'INVALID_INPUT' });
+    if (!raw)
+        throw invalid('ref is required: a handle such as T7K2QXD, a Ziggs URL, or an id from a prior response');
+    const ref = parseRef(raw);
+    if (!ref && looksLikeHandle(raw))
+        throw invalid(`${raw} is not a handle: its check letter does not match. Check it for a typo`);
+    const body = { ref: ref?.id ?? raw };
     if (typeof args['cursor'] === 'string')
         body.cursor = args['cursor'];
     if (typeof args['after'] === 'string')
@@ -304,7 +298,7 @@ function presentOpenResult(result, env) {
         const ask = row.grantRequest;
         if (row.status !== 'active' || !isContextAccessRequest(ask) || !actingAgentId || ask.holderId !== actingAgentId || !ask.scope?.id || !['artifact', 'chat', 'agreement', 'task'].includes(ask.scope.kind ?? ''))
             return [];
-        return [{ kind: 'resume', tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: { [`${ask.scope.kind}Id`]: ask.scope.id }, effect: 'read_only', note: 'Approval recorded. Open the original scope; the server rechecks expiry and revocation.' }];
+        return [{ kind: 'resume', tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: { ref: ask.scope.id }, effect: 'read_only', note: 'Approval recorded. Open the original scope; the server rechecks expiry and revocation.' }];
     });
     return {
         ...result,
@@ -353,16 +347,15 @@ export const openCapability = {
     names: { sdk: 'open', mcp: 'ziggs_open' },
     title: 'Open a returned resource',
     descriptions: {
-        sdk: 'Read a returned resource: pass exactly one of artifactId, chatId, taskId, agreementId. The backend resolves access and returns scoped actions with required inputs and recovery calls. Opening executes none of those actions. Extraction pending/failed is not an empty document. To read a chat\'s messages under one agreement, use context_read with type=messages, via=chat:<id> and agreementId.',
+        sdk: 'Read a returned resource: pass its ref, a short handle such as T7K2QXD (the first letter is the kind), a Ziggs URL, or an id. The backend resolves access and returns scoped actions with required inputs and recovery calls. Opening executes none of those actions. Extraction pending/failed is not an empty document. To read a chat\'s messages under one agreement, use context_read with type=messages, via=chat:<id> and its agreement filter.',
     },
     annotation: 'read-only',
-    // agreementId here is the agreement to open, one id among four
-    // (OPEN_ID_PARAMS). It used to carry context_read's filter wording, so an
+    // ref names the one record to open (OPEN_REF_PARAMS). It used to carry context_read's filter wording, so an
     // agent passed it beside chatId as a filter and was refused by the
     // exactly-one rule. Filtering a room's messages to one agreement is
     // context_read's job, and the description says so.
     params: {
-        ...OPEN_ID_PARAMS,
+        ...OPEN_REF_PARAMS,
         cursor: { type: 'string', description: 'Opaque cursor from a prior open page' },
         after: { type: 'string', description: 'ISO timestamp for a forward-delta' },
         limit: { type: 'number', description: 'Page size' },
@@ -379,10 +372,10 @@ export const accessExplainCapability = {
     names: { sdk: 'access_explain', mcp: 'ziggs_access_explain' },
     title: 'Explain access to a resource',
     descriptions: {
-        sdk: 'Read-only access explanation for an ordinary returned id. Same one-of artifactId/chatId/taskId/agreementId as open. Returns scoped action states, required inputs and recovery calls. Does not return content and does not request or approve anything.',
+        sdk: 'Read-only access explanation for a returned resource. Same ref as open. Returns scoped action states, required inputs and recovery calls. Does not return content and does not request or approve anything.',
     },
     annotation: 'read-only',
-    params: OPEN_ID_PARAMS,
+    params: OPEN_REF_PARAMS,
     needsAgentId: true,
     handler: async (args, env) => {
         const creds = fullCreds(env);
@@ -508,7 +501,7 @@ export const accessRequestCapability = {
             // A person scope opens nothing: the yes shows up in the chat list.
             ...(scopeKind === 'person'
                 ? env.surface === 'mcp' ? { resumeAfterApproval: { tool: 'ziggs_chat_list', args: {} } } : {}
-                : { resumeAfterApproval: { tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: result.scope ? { [`${result.scope.kind}Id`]: result.scope.id } : { [`${scopeKind}Id`]: scopeId } } }),
+                : { resumeAfterApproval: { tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: { ref: result.scope?.id ?? scopeId } } }),
             note: `${result.message ?? 'A request card is open.'} No access granted until they approve; then open the original resource using the same agent identity.`,
         };
     },

package/dist/capabilities/mcpBriefs.js

@@ -113,7 +113,7 @@ const BRIEFS = {
     },
     // Reading context
     ziggs_open: {
-        does: 'Reads one artifact, chat, task or agreement by id (exactly one id), with the actions you may take and any recovery call. Hidden and unknown look the same. A chat\'s messages under one agreement: ziggs_context_read with agreementId.',
+        does: 'Reads one task, agreement, chat or artifact by ref: a handle like T7K2QXD, a Ziggs URL or an id. Returns the actions you may take. Hidden and unknown look the same. Messages under one agreement: ziggs_context_read.',
     },
     ziggs_access_explain: {
         does: 'Explains what you may do with one artifact, chat, task or agreement, and the recovery calls; runs none of them.',

package/dist/handles.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Short handles: the id of a task (T…), agreement (A…), chat (C…) or
+ * artifact (F…). A kind letter, five to eight letters from 0-9 A-Z without
+ * I, L, O and U, and a check letter. Read in any case; written upper case.
+ *
+ * Mirrors the server's rule so a mistyped handle is refused here, before any
+ * call. The server stays the judge of what the handle opens.
+ */
+export declare const HANDLE_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export type HandleKind = 'task' | 'agreement' | 'chat' | 'artifact';
+/** The handle's kind and its upper-case form, or null when it is not one. */
+export declare function parseHandle(raw: string): {
+    kind: HandleKind;
+    id: string;
+} | null;
+/** The shape of a handle, whether or not its check letter holds. */
+export declare function looksLikeHandle(raw: string): boolean;
+/**
+ * What a `ref` names: a handle in any case, a Ziggs web URL that contains
+ * one, or an id of the older shape. Null when it names nothing.
+ */
+export declare function parseRef(raw: unknown): {
+    kind: HandleKind;
+    id: string;
+} | null;
+/**
+ * Every handle named in free text, in order and once each, so an agent that
+ * reads "look at T7K2QXD" can open it without anyone pasting a form. Words
+ * that merely look like one fail the check letter and are left out.
+ */
+export declare function findHandles(text: string): Array<{
+    kind: HandleKind;
+    id: string;
+}>;

package/dist/handles.js

@@ -0,0 +1,99 @@
+/**
+ * Short handles: the id of a task (T…), agreement (A…), chat (C…) or
+ * artifact (F…). A kind letter, five to eight letters from 0-9 A-Z without
+ * I, L, O and U, and a check letter. Read in any case; written upper case.
+ *
+ * Mirrors the server's rule so a mistyped handle is refused here, before any
+ * call. The server stays the judge of what the handle opens.
+ */
+export const HANDLE_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const LETTER_KIND = { T: 'task', A: 'agreement', C: 'chat', F: 'artifact' };
+const N = HANDLE_ALPHABET.length;
+function checkHolds(handle) {
+    let factor = 1;
+    let sum = 0;
+    for (let i = handle.length - 1; i >= 0; i--) {
+        let addend = factor * HANDLE_ALPHABET.indexOf(handle[i]);
+        factor = factor === 2 ? 1 : 2;
+        addend = Math.floor(addend / N) + (addend % N);
+        sum += addend;
+    }
+    return sum % N === 0;
+}
+/** The handle's kind and its upper-case form, or null when it is not one. */
+export function parseHandle(raw) {
+    const handle = raw.trim().toUpperCase();
+    if (handle.length < 7 || handle.length > 10)
+        return null;
+    if (![...handle].every((c) => HANDLE_ALPHABET.includes(c)))
+        return null;
+    const kind = LETTER_KIND[handle[0]];
+    if (!kind || !checkHolds(handle))
+        return null;
+    return { kind, id: handle };
+}
+const OLD_SHAPES = [
+    [/^task_[0-9a-f-]{36}$/, 'task'],
+    [/^agr_[A-Za-z0-9_]+$/, 'agreement'],
+    [/^(art_|org-state-)[A-Za-z0-9_-]+$/, 'artifact'],
+    [/^[a-z]{24}$/, 'chat'],
+];
+/** The shape of a handle, whether or not its check letter holds. */
+export function looksLikeHandle(raw) {
+    return /^[TACF][0-9A-Z]{6,9}$/i.test(raw.trim());
+}
+function parseOne(token) {
+    const trimmed = token.trim();
+    for (const [shape, kind] of OLD_SHAPES)
+        if (shape.test(trimmed))
+            return { kind, id: trimmed };
+    return parseHandle(trimmed);
+}
+/**
+ * What a `ref` names: a handle in any case, a Ziggs web URL that contains
+ * one, or an id of the older shape. Null when it names nothing.
+ */
+export function parseRef(raw) {
+    if (typeof raw !== 'string' || !raw.trim())
+        return null;
+    const value = raw.trim();
+    const direct = parseOne(value);
+    if (direct)
+        return direct;
+    if (!/[/?#]/.test(value))
+        return null;
+    let path = value;
+    try {
+        const url = new URL(value, 'https://ziggsai.com');
+        path = `${url.pathname}/${[...url.searchParams.values()].join('/')}`;
+    }
+    catch {
+        // Not a URL; split what was given.
+    }
+    for (const segment of path.split(/[/?#&=]/).reverse()) {
+        if (!segment)
+            continue;
+        const hit = parseOne(decodeURIComponent(segment));
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+const CANDIDATE = /\b[TACF][0-9A-HJKMNP-TV-Z]{6,9}\b/gi;
+/**
+ * Every handle named in free text, in order and once each, so an agent that
+ * reads "look at T7K2QXD" can open it without anyone pasting a form. Words
+ * that merely look like one fail the check letter and are left out.
+ */
+export function findHandles(text) {
+    const out = [];
+    const seen = new Set();
+    for (const match of text.matchAll(CANDIDATE)) {
+        const hit = parseHandle(match[0]);
+        if (hit && !seen.has(hit.id)) {
+            seen.add(hit.id);
+            out.push(hit);
+        }
+    }
+    return out;
+}

package/dist/http/ContextOpenClient.d.ts

@@ -6,6 +6,8 @@ export interface ContextOpenRef {
     id: string;
 }
 export interface ContextOpenBody {
+    /** A handle (T…/A…/C…/F…), a Ziggs URL holding one, or an older id. */
+    ref?: string;
     artifactId?: string;
     chatId?: string;
     taskId?: string;

package/dist/http/ContextOpenClient.js

@@ -31,11 +31,11 @@ export class ContextOpenClient {
         return this.post('/context/access/explain', body);
     }
     async post(path, body) {
-        const filled = ['artifactId', 'chatId', 'taskId', 'agreementId'].filter((key) => typeof body[key] === 'string' && body[key].trim());
+        const filled = ['ref', 'artifactId', 'chatId', 'taskId', 'agreementId'].filter((key) => typeof body[key] === 'string' && body[key].trim());
         if (filled.length !== 1) {
             // A caller's input mistake, named in the caller's words: the shared
             // INVALID_INPUT code, and no internal class name in the sentence.
-            throw Object.assign(new Error('Pass exactly one of artifactId, chatId, taskId, agreementId.'), { code: 'INVALID_INPUT' });
+            throw Object.assign(new Error('Pass ref (a handle such as T7K2QXD, a Ziggs URL, or an id), or exactly one of artifactId, chatId, taskId, agreementId.'), { code: 'INVALID_INPUT' });
         }
         const url = `${this.baseUrl || getBackendUrl()}${path}`;
         const res = await fetch(url, {

package/dist/index.d.ts

@@ -32,3 +32,4 @@ export type { EngagementGuide, EngagementGuideKind, EngagementOutcome, Engagemen
 export { isContextAccessRequest } from './shared/contextAccessRequest.js';
 export { AssistantConnectionClient, type AssistantWorkspace, } from './http/AssistantConnectionClient.js';
 export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHeaders.js';
+export { HANDLE_ALPHABET, findHandles, looksLikeHandle, parseHandle, parseRef, type HandleKind } from './handles.js';

package/dist/index.js

@@ -29,3 +29,5 @@ export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, forma
 export { isContextAccessRequest } from './shared/contextAccessRequest.js';
 export { AssistantConnectionClient, } from './http/AssistantConnectionClient.js';
 export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHeaders.js';
+// Short handles: T…, A…, C…, F… (task, agreement, chat, artifact).
+export { HANDLE_ALPHABET, findHandles, looksLikeHandle, parseHandle, parseRef } from './handles.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.37.10",
+  "version": "0.37.12",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",