@ziggs-ai/api-client 0.3.1 → 0.5.0

package/dist/http/OrgsClient.js

@@ -0,0 +1,61 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+/**
+ * ZIG-739 / ZIG-956 — the operator's full org membership (not just granted
+ * scopes, which is all the grant listers see). Lets a delegate resolve an org
+ * name to an id and offer a pick-list instead of demanding a pasted org_... id.
+ * Moved here from ziggs-mcp so every surface rides the one client (ZIG-894).
+ */
+export async function fetchMyOrgs(creds, baseUrl) {
+    const url = `${baseUrl || getBackendUrl()}/orgs/me`;
+    const res = await fetch(url, {
+        method: 'GET',
+        headers: buildOperatorHeaders(creds.operatorKey, creds.agentId),
+    });
+    const body = await res.text().catch(() => '');
+    if (!res.ok) {
+        throw new Error(`GET /orgs/me ${res.status} ${body.slice(0, 200)}`);
+    }
+    const parsed = body ? JSON.parse(body) : {};
+    return (parsed.orgs ?? []).map((o) => ({
+        orgId: o.orgId,
+        name: o.name,
+        kind: o.kind,
+        role: o.role,
+    }));
+}
+/**
+ * ZIG-739 — resolve an org selector (exact org_... id OR a name/handle) against
+ * the operator's memberships. Exact id wins; otherwise case-insensitive name
+ * match. Ambiguous names return the candidates rather than guessing.
+ */
+export function resolveOrgSelector(orgs, selector) {
+    const byId = orgs.find((o) => o.orgId === selector);
+    if (byId)
+        return { status: 'ok', orgId: byId.orgId };
+    const needle = selector.toLowerCase();
+    const byName = orgs.filter((o) => o.name.toLowerCase() === needle);
+    if (byName.length === 1)
+        return { status: 'ok', orgId: byName[0].orgId };
+    if (byName.length > 1)
+        return { status: 'ambiguous', matches: byName };
+    return { status: 'not-found' };
+}
+/**
+ * ZIG-640 / ZIG-956 — runtime acting org from the server (self-hire / agent
+ * row): GET /agents/claude-delegate/access. Moved here from ziggs-mcp's inline
+ * fetch (ZIG-894 "one client for every surface").
+ */
+export async function fetchDelegateAccess(creds, baseUrl) {
+    const url = `${baseUrl || getBackendUrl()}/agents/claude-delegate/access`;
+    const res = await fetch(url, {
+        method: 'GET',
+        headers: buildOperatorHeaders(creds.operatorKey, creds.agentId),
+    });
+    const body = await res.text().catch(() => '');
+    if (!res.ok) {
+        throw new Error(`GET /agents/claude-delegate/access ${res.status} ${body.slice(0, 200)}`);
+    }
+    return body ? JSON.parse(body) : {};
+}

package/dist/http/PaymentsClient.d.ts

@@ -11,6 +11,71 @@ export interface WalletBalance {
     balance: number;
     availableBalance: number;
 }
+export interface PaymentTransactionView {
+    transactionId?: string;
+    [key: string]: unknown;
+}
+/** A resolved wallet reference (GET /payments/wallets/resolve). */
+export interface WalletRef {
+    walletId?: string;
+    ownerId?: string;
+    currency?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+export type TransferResult = {
+    status: 'approval_required';
+    approvalId: string | null;
+    expiresAt: string | null;
+    reason: string | null;
+    toWalletId: string;
+    amount: number;
+} | {
+    status: 'transferred';
+    transactionId: string | null;
+    toWalletId: string;
+    amount: number;
+};
+export interface HoldResult {
+    transaction?: PaymentTransactionView;
+    [key: string]: unknown;
+}
+export interface ReleaseResult {
+    transaction?: PaymentTransactionView;
+    [key: string]: unknown;
+}
+export interface PaymentGrantView {
+    grantId?: string;
+    holderId?: string;
+    parentGrantId?: string;
+    caveats?: unknown[];
+    expiresAt?: string | null;
+    [key: string]: unknown;
+}
+export interface PaymentGrantEnvelope {
+    grant?: PaymentGrantView;
+    [key: string]: unknown;
+}
+export interface RevokeGrantResult {
+    revoked?: unknown;
+    [key: string]: unknown;
+}
+export interface PaymentApproval {
+    approvalId?: string;
+    status?: string;
+    executedTransactionId?: string | null;
+    [key: string]: unknown;
+}
+export type WaitForApprovalResult = {
+    status: 'gone';
+} | {
+    status: 'executed';
+    approval: PaymentApproval;
+    transactionId: string | null;
+} | {
+    status: 'rejected' | 'expired' | 'timeout';
+    approval: PaymentApproval;
+};
 /**
  * ZIG-894 — the one payments client for every surface (agent-sdk, ziggs-mcp,
  * scripts). Consolidates the former agent-sdk private ZiggsPayClient. Wallet
@@ -28,25 +93,25 @@ export declare class PaymentsClient {
     resolve({ userId, agentId }?: {
         userId?: string;
         agentId?: string;
-    }): Promise<unknown>;
+    }): Promise<WalletRef | null>;
     transfer({ to, amount, idempotencyKey, description, paymentGrantId, }: {
         to: string;
         amount: number;
         idempotencyKey?: string;
         description?: string;
         paymentGrantId?: string;
-    }): Promise<unknown>;
+    }): Promise<TransferResult>;
     hold({ amount, idempotencyKey, description, }: {
         amount: number;
         idempotencyKey?: string;
         description?: string;
-    }): Promise<unknown>;
+    }): Promise<HoldResult>;
     release({ holdId, action, toWalletId, idempotencyKey, }: {
         holdId: string;
         action?: string;
         toWalletId?: string;
         idempotencyKey?: string;
-    }): Promise<unknown>;
+    }): Promise<ReleaseResult>;
     history(params?: {
         limit?: number;
         offset?: number;
@@ -55,13 +120,13 @@ export declare class PaymentsClient {
     issueGrant({ holderId, caveats }: {
         holderId: string;
         caveats?: unknown;
-    }): Promise<unknown>;
+    }): Promise<PaymentGrantEnvelope>;
     attenuateGrant({ grantId, holderId, caveats, }: {
         grantId: string;
         holderId: string;
         caveats?: unknown;
-    }): Promise<unknown>;
-    revokeGrant(grantId: string): Promise<unknown>;
+    }): Promise<PaymentGrantEnvelope>;
+    revokeGrant(grantId: string): Promise<RevokeGrantResult>;
     /**
      * Live wallet grants the acting agent holds, via the unified GET /grants
      * (ZIG-648 retired GET /payments/grants), following the cursor to completion.
@@ -80,14 +145,14 @@ export declare class PaymentsClient {
     }): Promise<unknown>;
     approvals({ status }?: {
         status?: string;
-    }): Promise<unknown[]>;
-    getApproval(approvalId: string): Promise<unknown | null>;
+    }): Promise<PaymentApproval[]>;
+    getApproval(approvalId: string): Promise<PaymentApproval | null>;
     decide(approvalId: string, decision: string, note?: string): Promise<unknown>;
     waitForApproval(approvalId: string, opts?: {
         pollMs?: number;
         timeoutMs?: number;
         signal?: AbortSignal;
-    }): Promise<unknown>;
+    }): Promise<WaitForApprovalResult>;
     private _request;
     private _get;
     private _post;

package/dist/http/PaymentsClient.js

@@ -65,10 +65,10 @@ export class PaymentsClient {
             throw new Error('transfer: paymentGrantId is required for agent-impersonated transfers. The wallet owner must have issued a payment grant to this agentId.');
         let toWalletId = to;
         if (!to.startsWith('wal_')) {
-            const w = (await this.resolve(to.startsWith('agent_') ? { agentId: to } : { userId: to }));
-            if (!w?.['walletId'])
+            const w = await this.resolve(to.startsWith('agent_') ? { agentId: to } : { userId: to });
+            if (!w?.walletId)
                 throw new Error(`transfer: could not resolve wallet for "${to}"`);
-            toWalletId = w['walletId'];
+            toWalletId = w.walletId;
         }
         const result = (await this._post('/payments/transfer', {
             toWalletId,
@@ -89,23 +89,28 @@ export class PaymentsClient {
             };
         }
         const tx = result?.['transaction'];
-        return { status: 'transferred', transactionId: tx?.['transactionId'] || null, toWalletId, amount };
+        return {
+            status: 'transferred',
+            transactionId: tx?.['transactionId'] || null,
+            toWalletId,
+            amount,
+        };
     }
     async hold({ amount, idempotencyKey, description, }) {
         if (!(Number.isInteger(amount) && amount > 0))
             throw new Error('hold: `amount` must be a positive integer (cents)');
-        return this._post('/payments/hold', {
+        return (await this._post('/payments/hold', {
             amount,
             idempotencyKey: idempotencyKey || randomIdempotencyKey('hold'),
             description,
-        });
+        }));
     }
     async release({ holdId, action = 'complete', toWalletId, idempotencyKey, }) {
-        return this._post(`/payments/release/${holdId}`, {
+        return (await this._post(`/payments/release/${holdId}`, {
             idempotencyKey: idempotencyKey || randomIdempotencyKey('rel'),
             action,
             toWalletId,
-        });
+        }));
     }
     async history(params = {}) {
         const q = new URLSearchParams();
@@ -118,13 +123,16 @@ export class PaymentsClient {
         return this._get('/payments/history' + (q.toString() ? `?${q}` : ''));
     }
     async issueGrant({ holderId, caveats }) {
-        return this._post('/payments/grants', { holderId, caveats });
+        return (await this._post('/payments/grants', { holderId, caveats }));
     }
     async attenuateGrant({ grantId, holderId, caveats, }) {
-        return this._post(`/payments/grants/${grantId}/attenuate`, { holderId, caveats });
+        return (await this._post(`/payments/grants/${grantId}/attenuate`, {
+            holderId,
+            caveats,
+        }));
     }
     async revokeGrant(grantId) {
-        return this._request('DELETE', `/payments/grants/${grantId}`, undefined);
+        return (await this._request('DELETE', `/payments/grants/${grantId}`, undefined));
     }
     /**
      * Live wallet grants the acting agent holds, via the unified GET /grants
@@ -189,12 +197,16 @@ export class PaymentsClient {
         while (true) {
             if (signal?.aborted)
                 throw new Error('aborted');
-            const approval = (await this.getApproval(approvalId));
+            const approval = await this.getApproval(approvalId);
             if (!approval)
                 return { status: 'gone' };
-            const s = approval['status'];
+            const s = approval.status;
             if (s === 'executed')
-                return { status: 'executed', approval, transactionId: approval['executedTransactionId'] || null };
+                return {
+                    status: 'executed',
+                    approval,
+                    transactionId: approval.executedTransactionId || null,
+                };
             if (s === 'rejected')
                 return { status: 'rejected', approval };
             if (s === 'expired')

package/dist/http/index.d.ts

@@ -11,18 +11,18 @@ export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSna
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';
-export type { ListGrantsQuery, ListGrantsResult } from './GrantsClient.js';
+export type { ListGrantsQuery, ListGrantsResult, UnreadableRail } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, DelegateContextGrantResult, ReachEntry, GrantReachResult, } from './ContextGrantsClient.js';
 export { grantCaveat } from './grants.js';
 export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, } from './grants.js';
-export { decodeOperatorScopes, unreadableGrantRails } from './grantRails.js';
-export type { UnreadableRail } from './grantRails.js';
 export { PaymentsClient } from './PaymentsClient.js';
-export type { PaymentsError, WalletBalance } from './PaymentsClient.js';
+export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
-export type { ConnectionsError, ConnectionProxyParams, McpConnectionRequestParams, } from './ConnectionsClient.js';
+export type { ConnectionsError, ConnectionProxyParams, ConnectionGrant, ConnectionWithGrants, McpConnectionRequestParams, } from './ConnectionsClient.js';
+export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, } from './OrgsClient.js';
+export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
-export type { InboxScopeKind, InboxScopeEntry, InboxProposalRef, InboxConnectionRequestRef, InboxMcpServerRequestRef, InboxHumanAttention, InboxEnvelope, InboxAck, InboxAckResult, InboxOperatorAgentEntry, InboxOperatorEnvelope, } from './InboxClient.js';
+export type { InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxOperatorAgentEntry, InboxOperatorEnvelope, } from './InboxClient.js';

package/dist/http/index.js

@@ -9,9 +9,9 @@ export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export { grantCaveat } from './grants.js';
-export { decodeOperatorScopes, unreadableGrantRails } from './grantRails.js';
 export { PaymentsClient } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
+export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './http/index.js';
+export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
+export type { StartAgentOptions } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './http/index.js';
+export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';

package/package.json

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

package/dist/http/grantRails.d.ts

@@ -1,20 +0,0 @@
-import type { GrantScopeKind } from './grants.js';
-/**
- * Read the `scopes` claim of an operator JWT without verifying its signature —
- * an identity hint only, exactly as the backend re-checks the key row on every
- * request. Returns null when the token isn't a decodable JWT (so callers treat
- * entitlement as unknown rather than empty).
- */
-export declare function decodeOperatorScopes(operatorKey: string): string[] | null;
-export interface UnreadableRail {
-    rail: 'context' | 'connection' | 'wallet';
-    requiredScope: string;
-}
-/**
- * Which grant rails the operator key can't read, among those requested (or all
- * rails when no filter is given). Returns null when the key's scopes can't be
- * decoded — the caller then omits the "what I can't see" note rather than
- * guessing. `GET /grants` enforces the same boundary server-side; this only
- * lets the tool surface report it.
- */
-export declare function unreadableGrantRails(operatorKey: string, requested?: readonly GrantScopeKind[]): UnreadableRail[] | null;

package/dist/http/grantRails.js

@@ -1,50 +0,0 @@
-const RAIL_GROUPS = [
-    { rail: 'context', kinds: ['chat', 'agreement', 'org'], requiredScope: 'context:read' },
-    { rail: 'connection', kinds: ['connection'], requiredScope: 'connections:read' },
-    { rail: 'wallet', kinds: ['wallet'], requiredScope: 'payments:read' },
-];
-/**
- * Read the `scopes` claim of an operator JWT without verifying its signature —
- * an identity hint only, exactly as the backend re-checks the key row on every
- * request. Returns null when the token isn't a decodable JWT (so callers treat
- * entitlement as unknown rather than empty).
- */
-export function decodeOperatorScopes(operatorKey) {
-    const parts = (operatorKey ?? '').trim().split('.');
-    if (parts.length !== 3)
-        return null;
-    try {
-        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
-        const payload = JSON.parse(json);
-        if (!Array.isArray(payload.scopes))
-            return null;
-        return payload.scopes.filter((s) => typeof s === 'string');
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Which grant rails the operator key can't read, among those requested (or all
- * rails when no filter is given). Returns null when the key's scopes can't be
- * decoded — the caller then omits the "what I can't see" note rather than
- * guessing. `GET /grants` enforces the same boundary server-side; this only
- * lets the tool surface report it.
- */
-export function unreadableGrantRails(operatorKey, requested) {
-    const scopes = decodeOperatorScopes(operatorKey);
-    if (scopes === null)
-        return null;
-    const held = new Set(scopes);
-    const wanted = requested && requested.length > 0 ? new Set(requested) : null;
-    const out = [];
-    for (const group of RAIL_GROUPS) {
-        const inScope = wanted ? group.kinds.some((k) => wanted.has(k)) : true;
-        if (!inScope)
-            continue;
-        if (!held.has(group.requiredScope)) {
-            out.push({ rail: group.rail, requiredScope: group.requiredScope });
-        }
-    }
-    return out;
-}