@ziggs-ai/contracts 0.6.0 → 0.7.0

package/dist/credentials.d.ts

@@ -0,0 +1,47 @@
+/**
+ * How a credential was authorized.
+ *
+ * The server stamps this on every operator key it mints, and clients read it
+ * back: `isDirectoryBoarded` — is this an assistant that boarded through the
+ * connector directory, and therefore gets the listed tool surface rather than
+ * the whole one — is a predicate over exactly this set.
+ *
+ * It lives here because both sides need the same answer and neither owns it.
+ * The backend schema held the list and api-client restated the two values it
+ * happened to care about, so a rail added on the server was invisible to the
+ * client until somebody remembered: a third consent door would have served
+ * the full catalogue to every credential from it.
+ *
+ * The values record how the credential was AUTHORIZED, never which UI the
+ * person was looking at. "Dashboard" and "API/SDK" were the obvious pair to
+ * want and cannot be told apart: one route serves both, and a signed-in human
+ * and a script under a user session arrive identically. Recording "dashboard"
+ * would be a guess dressed as a fact.
+ */
+export declare const OPERATOR_KEY_ISSUED_VIA: {
+    /** The default key minted for a new account at registration. */
+    readonly SIGNUP: "signup";
+    /** `POST /operator-tokens` under a signed-in human's session. */
+    readonly SESSION: "session";
+    /** `POST /operator-tokens` from another operator key; `issuedByKeyId` says which. */
+    readonly DERIVED: "derived";
+    /** The agent-bound key minted by agent create or rotate. */
+    readonly AGENT_PROVISIONING: "agent_provisioning";
+    /** The MCP OAuth authorization-code consent flow. */
+    readonly MCP_OAUTH: "mcp_oauth";
+    /** The MCP OAuth device-code flow. */
+    readonly DEVICE_CODE: "device_code";
+};
+export type OperatorKeyIssuedVia = (typeof OPERATOR_KEY_ISSUED_VIA)[keyof typeof OPERATOR_KEY_ISSUED_VIA];
+/**
+ * The doors that board a connected assistant through the connector directory.
+ *
+ * Ask this rather than comparing to one value. Both consent rails board an
+ * assistant the same way and both want the same narrowed surface, but the
+ * server records them as the different acts they are — an equality test
+ * against one of them serves the whole catalogue to every credential from the
+ * other.
+ */
+export declare const DIRECTORY_BOARDED_ISSUED_VIA: readonly OperatorKeyIssuedVia[];
+/** Did a person board this credential through the connector directory? */
+export declare function isDirectoryBoardedIssuedVia(issuedVia: string | null | undefined): boolean;

package/dist/credentials.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIRECTORY_BOARDED_ISSUED_VIA = exports.OPERATOR_KEY_ISSUED_VIA = void 0;
+exports.isDirectoryBoardedIssuedVia = isDirectoryBoardedIssuedVia;
+/**
+ * How a credential was authorized.
+ *
+ * The server stamps this on every operator key it mints, and clients read it
+ * back: `isDirectoryBoarded` — is this an assistant that boarded through the
+ * connector directory, and therefore gets the listed tool surface rather than
+ * the whole one — is a predicate over exactly this set.
+ *
+ * It lives here because both sides need the same answer and neither owns it.
+ * The backend schema held the list and api-client restated the two values it
+ * happened to care about, so a rail added on the server was invisible to the
+ * client until somebody remembered: a third consent door would have served
+ * the full catalogue to every credential from it.
+ *
+ * The values record how the credential was AUTHORIZED, never which UI the
+ * person was looking at. "Dashboard" and "API/SDK" were the obvious pair to
+ * want and cannot be told apart: one route serves both, and a signed-in human
+ * and a script under a user session arrive identically. Recording "dashboard"
+ * would be a guess dressed as a fact.
+ */
+exports.OPERATOR_KEY_ISSUED_VIA = {
+    /** The default key minted for a new account at registration. */
+    SIGNUP: 'signup',
+    /** `POST /operator-tokens` under a signed-in human's session. */
+    SESSION: 'session',
+    /** `POST /operator-tokens` from another operator key; `issuedByKeyId` says which. */
+    DERIVED: 'derived',
+    /** The agent-bound key minted by agent create or rotate. */
+    AGENT_PROVISIONING: 'agent_provisioning',
+    /** The MCP OAuth authorization-code consent flow. */
+    MCP_OAUTH: 'mcp_oauth',
+    /** The MCP OAuth device-code flow. */
+    DEVICE_CODE: 'device_code',
+};
+/**
+ * The doors that board a connected assistant through the connector directory.
+ *
+ * Ask this rather than comparing to one value. Both consent rails board an
+ * assistant the same way and both want the same narrowed surface, but the
+ * server records them as the different acts they are — an equality test
+ * against one of them serves the whole catalogue to every credential from the
+ * other.
+ */
+exports.DIRECTORY_BOARDED_ISSUED_VIA = [
+    exports.OPERATOR_KEY_ISSUED_VIA.MCP_OAUTH,
+    exports.OPERATOR_KEY_ISSUED_VIA.DEVICE_CODE,
+];
+/** Did a person board this credential through the connector directory? */
+function isDirectoryBoardedIssuedVia(issuedVia) {
+    return exports.DIRECTORY_BOARDED_ISSUED_VIA.includes(issuedVia);
+}

package/dist/error.d.ts

@@ -3,9 +3,18 @@
  *
  * Every handler error is rendered as this body with an HTTP status, so a
  * client can render the real message instead of a boolean.
+ *
+ * `code` is the machine-readable reason, present when the handler supplied
+ * one (`GRANT_REVOKED`, `GRANT_PARTY_MISMATCH`, `NO_USER_CONNECTION`, …). The
+ * global filter has emitted it since ZIG-702 and api-client has read it since
+ * then, and this contract did not say so — which is how a shape meant to be
+ * the one description of the wire came to describe less of it than both sides
+ * already relied on. A client branching on `code` is the point: `error` is for
+ * a person to read, `code` is for a program to decide with.
  */
 export interface ApiErrorBody {
     error: string;
+    code?: string;
 }
 /** True when a response body is the API's error shape. */
 export declare function isApiErrorBody(body: unknown): body is ApiErrorBody;

package/dist/generated/agreements.d.ts

@@ -0,0 +1,113 @@
+/**
+ * GENERATED from the backend OpenAPI spec — do not edit.
+ * Family: agreements. Regenerate: backend 'pnpm docs:generate' then this script.
+ */
+export type AgreementPartySide = {
+    principal: string | null;
+    actor: string | null;
+};
+export type AgreementParties = {
+    payer: AgreementPartySide;
+    provider: AgreementPartySide;
+    proposedTo: AgreementPartySide;
+    creator: AgreementPartySide;
+};
+export type AgreementTerms = {
+    lifecycle: "open" | "time-bound" | "count-bound";
+    expiresAt: string | null;
+    maxExecutions: number | null;
+    description: string;
+    billing?: "total" | "per_task";
+    requiredConnections: Array<unknown>;
+    wakeCeiling?: number;
+};
+export type AgreementHeld = {
+    amount: number;
+    currency: "pez";
+    state: "held" | "released" | "refunded";
+    agreementId: string;
+};
+export type AgreementAllocation = {
+    childAgreementId: string;
+    childTaskId: string | null;
+    amount: number;
+    status: "allocated" | "completed" | "released" | "failed";
+};
+export type AgreementMoney = {
+    price: number | null;
+    paymentStatus: "none" | "held" | "allocated" | "paid" | "refunded" | "metered";
+    transactionId: string | null;
+    allocations: Array<AgreementAllocation>;
+    held: AgreementHeld | null;
+};
+export type AgreementProposal = {
+    status: "pending" | "approved" | "rejected" | "expired" | "countered" | null;
+    respondedBy: string | null;
+    proposedAt: string | null;
+    respondedAt: string | null;
+};
+export type AgreementApproval = {
+    partyId: string;
+    role: "payer" | "provider" | "proposedTo" | "principal";
+    status: "pending" | "self-consent" | "approved" | "rejected";
+    respondedAt: string | null;
+    respondedBy?: string | null;
+};
+export type AgreementUserReport = {
+    userId: string;
+    message: string;
+    createdAt: string;
+};
+export type AgreementActivationFailure = {
+    message: string;
+    at: string;
+};
+export type AgreementClaimSeats = {
+    maxClaims: number | null;
+    claimsUsed: number;
+};
+export type AgreementConnectionRequest = {
+    serverUrl: string;
+    tools: Array<string>;
+    reason: string | null;
+    connectionReady: boolean;
+};
+export type AgreementRead = {
+    agreementId: string;
+    rootAgreementId: string | null;
+    parentAgreementId: string | null;
+    parties: AgreementParties;
+    terms: AgreementTerms;
+    money: AgreementMoney;
+    proposal: AgreementProposal;
+    status: "draft" | "open" | "active" | "fulfilled" | "cancelled" | "refunded";
+    engagementKind: "hire" | "service" | "link";
+    formedBy: "principal" | "agent";
+    orgId: string | null;
+    userOutcomeSatisfaction: "positive" | "negative" | null;
+    approvals: Array<AgreementApproval>;
+    userReports: Array<AgreementUserReport>;
+    activationFailure: AgreementActivationFailure | null;
+    providerPinned: boolean;
+    claimSeats: AgreementClaimSeats | null;
+    listingPausedAt?: string | null;
+    metadata: Record<string, unknown>;
+    connectionRequest?: AgreementConnectionRequest;
+    createdAt: string;
+    updatedAt: string;
+    partyPresentations?: Record<string, unknown>;
+    peer?: {
+        id?: string;
+        name?: string;
+    };
+    hireClosed?: {
+        kind?: "dark" | "paused" | "full";
+        reason?: string;
+    } | null;
+};
+export type AgreementGetResponse = {
+    agreement: AgreementRead;
+};
+export type AgreementListResponse = {
+    agreements: Array<AgreementRead>;
+};

package/dist/generated/agreements.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -10,11 +10,13 @@ export * from './vocabulary';
 export * from './chat';
 export * from './inbox';
 export * from './error';
+export * from './credentials';
 export * from './socket';
 export * from './generated/agents';
 export * from './generated/grants';
 export * from './generated/payments';
 export * from './generated/connections';
+export * from './generated/agreements';
 export * from './generated/artifacts';
 export * from './identifiers';
 export * from './generated/chat-send';

package/dist/index.js

@@ -26,12 +26,14 @@ __exportStar(require("./vocabulary"), exports);
 __exportStar(require("./chat"), exports);
 __exportStar(require("./inbox"), exports);
 __exportStar(require("./error"), exports);
+__exportStar(require("./credentials"), exports);
 __exportStar(require("./socket"), exports);
 // Generated from the backend OpenAPI spec (ZIG-1668). See scripts/generate-wire.mjs.
 __exportStar(require("./generated/agents"), exports);
 __exportStar(require("./generated/grants"), exports);
 __exportStar(require("./generated/payments"), exports);
 __exportStar(require("./generated/connections"), exports);
+__exportStar(require("./generated/agreements"), exports);
 __exportStar(require("./generated/artifacts"), exports);
 __exportStar(require("./identifiers"), exports);
 __exportStar(require("./generated/chat-send"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/contracts",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Wire contracts for the Ziggs API — response shapes, error body, and socket events, shared by every client.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",