zanii-connect 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# zanii-connect — TypeScript SDK
+
+TypeScript/JavaScript client for [Zanii Connect](https://vault.zanii.agency/api/docs): OAuth
+connections, encrypted token vault, and audited tool execution for AI agents.
+
+**Zero runtime dependencies** — uses the platform `fetch` (Node 18+, browsers, edge runtimes).
+
+## Install & build
+
+```bash
+cd sdk/typescript && npm install && npm run build   # from the monorepo
+```
+
+## Quickstart
+
+```ts
+import { ZaniiClient } from "zanii-connect";
+
+// Agents/services authenticate with a scoped API key:
+const nc = new ZaniiClient({ apiKey: "nsk_..." });
+
+// Or as a user (JWT):
+const nc = new ZaniiClient();
+await nc.login("info@zanii.agency", "password");
+
+console.log((await nc.me()).organization.name);
+
+// Connect a provider (open the returned URL in a browser to complete OAuth):
+const { url } = await nc.connect("gmail",
+  "https://vault.zanii.agency/api/v1/connect/oauth/callback");
+
+// Discover tools and execute one:
+const conn = (await nc.connections()).connections[0];
+const found = await nc.execute("gmail.search", conn.id, { query: "invoice" });
+
+// Actions that need human approval return an approval link instead of executing:
+const res = await nc.execute("gmail.sendEmail", conn.id,
+  { to: "info@zanii.agency", subject: "Hi", body: "Hello" });
+if (res.requires_approval) console.log("Ask a human to confirm:", res.approval_url);
+
+// Long-running work goes through the job queue:
+const job = await nc.executeAsync("browser.run", conn.id, { /* ... */ });
+const result = await nc.waitForJob(job.job_id, 300);
+```
+
+## Behavior
+
+- **Retries**: 429/502/503/504 are retried up to 3 times with exponential backoff.
+- **Idempotency**: pass `{ idempotencyKey }` to `execute()` to make retries safe for side-effecting actions.
+- **Errors**: non-2xx responses throw `ZaniiError` with `.statusCode` and `.detail`.
+- **MCP**: AI agents that speak MCP don't need this SDK — point them at
+  `POST https://vault.zanii.agency/api/v1/mcp` with an `X-API-Key` header.
+
+## Surface
+
+Mirrors the Python SDK (`sdk/python`), camelCased — covers the full API:
+
+- **Account**: `signup`, `login`, `me`, `updateProfile`, `changePassword`, `forgotPassword`, `resetPassword`, email verification, MFA (`mfaEnroll`/`mfaEnable`/`mfaDisable`)
+- **API keys**: `createApiKey` (plaintext returned once), `apiKeys`, `deleteApiKey` (soft revoke)
+- **Org & team**: `org`, `usage`, `updateOrg`, `exportOrg`, `deleteOrg`, `users`, `inviteUser`, `updateUser`, `deactivateUser`, roles (`permissions`, `roles`, `upsertRole`, `deleteRole`), workspaces/projects/environments
+- **Registry**: `providers`, `provider`, `providerActions`, `actions`, `action`, `tools`, `tool`, dynamic-registry admin (`registerProvider`, `registerAction`, `unregisterAction`)
+- **Connections**: `connect`, `connections`, `connectionsHealth`, `deleteConnection`, `shareConnection`
+- **Execution**: `execute`, `executeAsync`, `job`, `waitForJob` · approvals (`approvals`, `approve`)
+- **Browser sandbox**: `createBrowserSession`, `browserSession`, `browserRun`, `browserRunAsync`
+- **Secrets / automation**: `secrets`, `setSecret`, `deleteSecret`, triggers, webhook subscriptions
+- **Observability**: `executions`, `audit`, `auditExportCsv`, `health`

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Zanii Connect SDK.
+ *
+ *   import { ZaniiClient } from "zanii-connect";
+ *
+ *   const nc = new ZaniiClient({ apiKey: "nsk_..." });        // agents / services
+ *   // or a user session:
+ *   const nc = new ZaniiClient();
+ *   await nc.login("info@zanii.agency", "password");
+ *
+ *   const tools = await nc.tools();
+ *   const res = await nc.execute("gmail.search", connId, { query: "invoice" });
+ *
+ * Zero dependencies — uses the platform fetch (Node 18+, browsers, edge).
+ */
+export declare const DEFAULT_BASE_URL = "https://vault.zanii.agency/api/v1";
+export declare class ZaniiError extends Error {
+    statusCode: number;
+    detail: string;
+    constructor(statusCode: number, detail: string);
+}
+export declare class JobTimeout extends ZaniiError {
+    jobId: string;
+    constructor(jobId: string, timeoutSeconds: number);
+}
+export interface ZaniiClientOptions {
+    apiKey?: string;
+    token?: string;
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default 60 000). */
+    timeoutMs?: number;
+}
+export declare class ZaniiClient {
+    private baseUrl;
+    private apiKey?;
+    private token?;
+    private timeoutMs;
+    constructor(opts?: ZaniiClientOptions);
+    private req;
+    /** Service health incl. dependency checks (no auth required). */
+    health(): Promise<any>;
+    /** Create a new organization + first admin user. Returns a session token. */
+    signup(orgName: string, orgSlug: string, email: string, name: string, password: string): Promise<any>;
+    /** Log in with email/password; stores the JWT on the client. */
+    login(email: string, password: string, mfaCode?: string): Promise<any>;
+    /** Current user, organization, role, and effective permissions. */
+    me(): Promise<any>;
+    updateProfile(name: string): Promise<any>;
+    changePassword(currentPassword: string, newPassword: string): Promise<any>;
+    forgotPassword(email: string): Promise<any>;
+    resetPassword(token: string, newPassword: string): Promise<any>;
+    requestEmailVerification(): Promise<any>;
+    confirmEmailVerification(token: string): Promise<any>;
+    /** Begin TOTP enrollment. Returns the otpauth secret/URI to show the user. */
+    mfaEnroll(): Promise<any>;
+    mfaEnable(code: string): Promise<any>;
+    mfaDisable(code: string): Promise<any>;
+    /** Create a scoped API key. The plaintext key is returned ONCE. */
+    createApiKey(name: string, scopes?: string[]): Promise<any>;
+    apiKeys(): Promise<any>;
+    /** Revoke an API key (kept in the list with revoked=true for audit). */
+    deleteApiKey(keyId: string): Promise<any>;
+    org(): Promise<any>;
+    /** Current-month execution usage vs quota. */
+    usage(): Promise<any>;
+    /** Update status / plan / monthly_execution_quota (admin). */
+    updateOrg(fields: {
+        status?: string;
+        plan?: string;
+        monthly_execution_quota?: number;
+    }): Promise<any>;
+    /** Portable JSON export of all tenant data (GDPR, admin). */
+    exportOrg(): Promise<any>;
+    /** Hard-delete the organization and ALL tenant data (GDPR erasure, admin). */
+    deleteOrg(): Promise<any>;
+    users(): Promise<any>;
+    /** Invite a teammate. Without password they get a set-your-password email. */
+    inviteUser(email: string, name: string, role?: string, password?: string): Promise<any>;
+    updateUser(userId: string, fields: {
+        role?: string;
+        is_active?: boolean;
+    }): Promise<any>;
+    deactivateUser(userId: string): Promise<any>;
+    /** The full permission catalog custom roles may grant from. */
+    permissions(): Promise<any>;
+    roles(): Promise<any>;
+    upsertRole(name: string, permissions: string[]): Promise<any>;
+    deleteRole(name: string): Promise<any>;
+    workspaces(): Promise<any>;
+    createWorkspace(name: string, slug?: string): Promise<any>;
+    deleteWorkspace(workspaceId: string): Promise<any>;
+    projects(): Promise<any>;
+    createProject(name: string, description?: string): Promise<any>;
+    deleteProject(projectId: string): Promise<any>;
+    environments(projectId: string): Promise<any>;
+    createEnvironment(projectId: string, name: string, slug?: string): Promise<any>;
+    providers(): Promise<any>;
+    provider(name: string): Promise<any>;
+    providerActions(provider: string): Promise<any>;
+    actions(provider?: string): Promise<any>;
+    action(name: string): Promise<any>;
+    /** Admin: register a runtime-defined provider in the dynamic registry. */
+    registerProvider(provider: Record<string, unknown>): Promise<any>;
+    /** Admin: register a runtime-defined action (generic REST mapping). */
+    registerAction(action: Record<string, unknown>): Promise<any>;
+    unregisterAction(name: string): Promise<any>;
+    /** MCP-shaped tool list (name, description, input_schema). */
+    tools(provider?: string): Promise<any>;
+    tool(name: string): Promise<any>;
+    /** Start OAuth for a provider. Returns { url } to open in a browser. */
+    connect(provider: string, redirectUrl: string): Promise<any>;
+    connections(): Promise<any>;
+    /** Per-connection health with needs_reauth flags. */
+    connectionsHealth(): Promise<any>;
+    deleteConnection(connectionId: string): Promise<any>;
+    shareConnection(connectionId: string, shared?: boolean): Promise<any>;
+    /**
+     * Run a tool synchronously. If the action needs human approval the response
+     * has status="pending" and an approval_url to hand to a human.
+     */
+    execute(action: string, connectionId: string, parameters?: Record<string, unknown>, opts?: {
+        idempotencyKey?: string;
+    }): Promise<any>;
+    /** Queue a long-running tool job. Returns { job_id, status }. */
+    executeAsync(action: string, connectionId: string, parameters?: Record<string, unknown>): Promise<any>;
+    job(jobId: string): Promise<any>;
+    /** Poll a job until it finishes. Throws JobTimeout on deadline. */
+    waitForJob(jobId: string, timeoutSeconds?: number, pollIntervalSeconds?: number): Promise<any>;
+    /** Start a Playwright browser session for no-API automation. */
+    createBrowserSession(targetUrl: string): Promise<any>;
+    browserSession(sessionId: string): Promise<any>;
+    /** Run browser steps (navigate/click/fill/extract/...) synchronously. */
+    browserRun(sessionId: string, steps: Record<string, unknown>[]): Promise<any>;
+    /** Queue browser steps as a job. Poll with job()/waitForJob(). */
+    browserRunAsync(sessionId: string, steps: Record<string, unknown>[]): Promise<any>;
+    approvals(status?: string, limit?: number, offset?: number): Promise<any>;
+    /** Decide a pending approval as the requesting user (JWT auth). */
+    approve(approvalId: string, approved?: boolean): Promise<any>;
+    secrets(): Promise<any>;
+    setSecret(name: string, value: string): Promise<any>;
+    deleteSecret(name: string): Promise<any>;
+    triggers(): Promise<any>;
+    createTrigger(trigger: Record<string, unknown>): Promise<any>;
+    deleteTrigger(triggerId: string): Promise<any>;
+    webhookSubscriptions(): Promise<any>;
+    createWebhookSubscription(subscription: Record<string, unknown>): Promise<any>;
+    deleteWebhookSubscription(subscriptionId: string): Promise<any>;
+    executions(opts?: {
+        action?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<any>;
+    audit(opts?: {
+        action?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<any>;
+    /** Full audit log as CSV text. */
+    auditExportCsv(): Promise<string>;
+}

package/dist/index.js

@@ -0,0 +1,389 @@
+/**
+ * Zanii Connect SDK.
+ *
+ *   import { ZaniiClient } from "zanii-connect";
+ *
+ *   const nc = new ZaniiClient({ apiKey: "nsk_..." });        // agents / services
+ *   // or a user session:
+ *   const nc = new ZaniiClient();
+ *   await nc.login("info@zanii.agency", "password");
+ *
+ *   const tools = await nc.tools();
+ *   const res = await nc.execute("gmail.search", connId, { query: "invoice" });
+ *
+ * Zero dependencies — uses the platform fetch (Node 18+, browsers, edge).
+ */
+export const DEFAULT_BASE_URL = "https://vault.zanii.agency/api/v1";
+const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+const RETRIES = 3;
+export class ZaniiError extends Error {
+    statusCode;
+    detail;
+    constructor(statusCode, detail) {
+        super(`[${statusCode}] ${detail}`);
+        this.statusCode = statusCode;
+        this.detail = detail;
+        this.name = "ZaniiError";
+    }
+}
+export class JobTimeout extends ZaniiError {
+    jobId;
+    constructor(jobId, timeoutSeconds) {
+        super(408, `Job ${jobId} still running after ${timeoutSeconds}s`);
+        this.jobId = jobId;
+        this.name = "JobTimeout";
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class ZaniiClient {
+    baseUrl;
+    apiKey;
+    token;
+    timeoutMs;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.apiKey = opts.apiKey;
+        this.token = opts.token;
+        this.timeoutMs = opts.timeoutMs ?? 60_000;
+    }
+    async req(method, path, o = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(o.params ?? {})) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+        const headers = { ...o.headers };
+        if (!o.noauth) {
+            if (this.apiKey)
+                headers["X-API-Key"] = this.apiKey;
+            else if (this.token)
+                headers["Authorization"] = `Bearer ${this.token}`;
+        }
+        if (o.json !== undefined)
+            headers["Content-Type"] = "application/json";
+        let resp;
+        for (let attempt = 0;; attempt++) {
+            resp = await fetch(url, {
+                method,
+                headers,
+                body: o.json !== undefined ? JSON.stringify(o.json) : undefined,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            if (RETRY_STATUSES.has(resp.status) && attempt < RETRIES) {
+                await sleep(Math.min(2 ** attempt, 8) * 1000);
+                continue;
+            }
+            break;
+        }
+        if (resp.status >= 400) {
+            let detail = await resp.text();
+            try {
+                detail = JSON.parse(detail).detail ?? detail;
+            }
+            catch {
+                /* plain-text error body */
+            }
+            throw new ZaniiError(resp.status, detail);
+        }
+        return o.raw ? resp.text() : resp.json();
+    }
+    // -- platform ---------------------------------------------------------
+    /** Service health incl. dependency checks (no auth required). */
+    health() {
+        return this.req("GET", "/health", { noauth: true });
+    }
+    // -- identity / account -------------------------------------------------
+    /** Create a new organization + first admin user. Returns a session token. */
+    signup(orgName, orgSlug, email, name, password) {
+        return this.req("POST", "/auth/signup", {
+            noauth: true,
+            json: { org_name: orgName, org_slug: orgSlug, email, name, password },
+        });
+    }
+    /** Log in with email/password; stores the JWT on the client. */
+    async login(email, password, mfaCode) {
+        const result = await this.req("POST", "/auth/login", {
+            noauth: true,
+            json: { email, password, ...(mfaCode ? { mfa_code: mfaCode } : {}) },
+        });
+        this.token = result.token;
+        return result;
+    }
+    /** Current user, organization, role, and effective permissions. */
+    me() {
+        return this.req("GET", "/auth/me");
+    }
+    updateProfile(name) {
+        return this.req("PATCH", "/users/me", { json: { name } });
+    }
+    changePassword(currentPassword, newPassword) {
+        return this.req("POST", "/auth/password/change", {
+            json: { current_password: currentPassword, new_password: newPassword },
+        });
+    }
+    forgotPassword(email) {
+        return this.req("POST", "/auth/password/forgot", { noauth: true, json: { email } });
+    }
+    resetPassword(token, newPassword) {
+        return this.req("POST", "/auth/password/reset", {
+            noauth: true,
+            json: { token, new_password: newPassword },
+        });
+    }
+    requestEmailVerification() {
+        return this.req("POST", "/auth/verify/request");
+    }
+    confirmEmailVerification(token) {
+        return this.req("POST", "/auth/verify/confirm", { noauth: true, json: { token } });
+    }
+    /** Begin TOTP enrollment. Returns the otpauth secret/URI to show the user. */
+    mfaEnroll() {
+        return this.req("POST", "/auth/mfa/enroll");
+    }
+    mfaEnable(code) {
+        return this.req("POST", "/auth/mfa/enable", { json: { code } });
+    }
+    mfaDisable(code) {
+        return this.req("POST", "/auth/mfa/disable", { json: { code } });
+    }
+    // -- API keys (for agents/services) ---------------------------------------
+    /** Create a scoped API key. The plaintext key is returned ONCE. */
+    createApiKey(name, scopes) {
+        return this.req("POST", "/auth/keys", { json: { name, scopes } });
+    }
+    apiKeys() {
+        return this.req("GET", "/auth/keys");
+    }
+    /** Revoke an API key (kept in the list with revoked=true for audit). */
+    deleteApiKey(keyId) {
+        return this.req("DELETE", `/auth/keys/${keyId}`);
+    }
+    // -- organization ---------------------------------------------------------
+    org() {
+        return this.req("GET", "/org");
+    }
+    /** Current-month execution usage vs quota. */
+    usage() {
+        return this.req("GET", "/org/usage");
+    }
+    /** Update status / plan / monthly_execution_quota (admin). */
+    updateOrg(fields) {
+        return this.req("PATCH", "/org", { json: fields });
+    }
+    /** Portable JSON export of all tenant data (GDPR, admin). */
+    exportOrg() {
+        return this.req("GET", "/org/export");
+    }
+    /** Hard-delete the organization and ALL tenant data (GDPR erasure, admin). */
+    deleteOrg() {
+        return this.req("DELETE", "/org");
+    }
+    // -- users ------------------------------------------------------------------
+    users() {
+        return this.req("GET", "/users");
+    }
+    /** Invite a teammate. Without password they get a set-your-password email. */
+    inviteUser(email, name, role = "member", password) {
+        return this.req("POST", "/users", {
+            json: { email, name, role, ...(password ? { password } : {}) },
+        });
+    }
+    updateUser(userId, fields) {
+        return this.req("PATCH", `/users/${userId}`, { json: fields });
+    }
+    deactivateUser(userId) {
+        return this.req("DELETE", `/users/${userId}`);
+    }
+    // -- roles / permissions ------------------------------------------------------
+    /** The full permission catalog custom roles may grant from. */
+    permissions() {
+        return this.req("GET", "/roles/permissions");
+    }
+    roles() {
+        return this.req("GET", "/roles");
+    }
+    upsertRole(name, permissions) {
+        return this.req("PUT", "/roles", { json: { name, permissions } });
+    }
+    deleteRole(name) {
+        return this.req("DELETE", `/roles/${name}`);
+    }
+    // -- workspaces / projects ------------------------------------------------------
+    workspaces() {
+        return this.req("GET", "/workspaces");
+    }
+    createWorkspace(name, slug) {
+        return this.req("POST", "/workspaces", { json: { name, slug } });
+    }
+    deleteWorkspace(workspaceId) {
+        return this.req("DELETE", `/workspaces/${workspaceId}`);
+    }
+    projects() {
+        return this.req("GET", "/projects");
+    }
+    createProject(name, description) {
+        return this.req("POST", "/projects", { json: { name, description } });
+    }
+    deleteProject(projectId) {
+        return this.req("DELETE", `/projects/${projectId}`);
+    }
+    environments(projectId) {
+        return this.req("GET", `/projects/${projectId}/environments`);
+    }
+    createEnvironment(projectId, name, slug) {
+        return this.req("POST", `/projects/${projectId}/environments`, { json: { name, slug } });
+    }
+    // -- registry / tools ---------------------------------------------------------
+    providers() {
+        return this.req("GET", "/registry/providers");
+    }
+    provider(name) {
+        return this.req("GET", `/registry/providers/${name}`);
+    }
+    providerActions(provider) {
+        return this.req("GET", `/registry/providers/${provider}/actions`);
+    }
+    actions(provider) {
+        return this.req("GET", "/registry/actions", { params: { provider } });
+    }
+    action(name) {
+        return this.req("GET", `/registry/actions/${name}`);
+    }
+    /** Admin: register a runtime-defined provider in the dynamic registry. */
+    registerProvider(provider) {
+        return this.req("POST", "/registry/providers", { json: provider });
+    }
+    /** Admin: register a runtime-defined action (generic REST mapping). */
+    registerAction(action) {
+        return this.req("POST", "/registry/actions", { json: action });
+    }
+    unregisterAction(name) {
+        return this.req("DELETE", `/registry/actions/${name}`);
+    }
+    /** MCP-shaped tool list (name, description, input_schema). */
+    tools(provider) {
+        return this.req("GET", "/tools", { params: { provider } });
+    }
+    tool(name) {
+        return this.req("GET", `/tools/${name}`);
+    }
+    // -- connections -----------------------------------------------------------
+    /** Start OAuth for a provider. Returns { url } to open in a browser. */
+    connect(provider, redirectUrl) {
+        return this.req("POST", "/connect", { json: { provider, redirect_url: redirectUrl } });
+    }
+    connections() {
+        return this.req("GET", "/connect/connections");
+    }
+    /** Per-connection health with needs_reauth flags. */
+    connectionsHealth() {
+        return this.req("GET", "/connect/connections/health");
+    }
+    deleteConnection(connectionId) {
+        return this.req("DELETE", `/connect/connection/${connectionId}`);
+    }
+    shareConnection(connectionId, shared = true) {
+        return this.req("PATCH", `/connect/connection/${connectionId}/share`, {
+            params: { shared },
+        });
+    }
+    // -- execution ---------------------------------------------------------------
+    /**
+     * Run a tool synchronously. If the action needs human approval the response
+     * has status="pending" and an approval_url to hand to a human.
+     */
+    execute(action, connectionId, parameters = {}, opts = {}) {
+        return this.req("POST", "/tools/execute", {
+            headers: opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : undefined,
+            json: { action, connection_id: connectionId, parameters },
+        });
+    }
+    /** Queue a long-running tool job. Returns { job_id, status }. */
+    executeAsync(action, connectionId, parameters = {}) {
+        return this.req("POST", "/tools/execute_async", {
+            json: { action, connection_id: connectionId, parameters },
+        });
+    }
+    job(jobId) {
+        return this.req("GET", `/jobs/${jobId}`);
+    }
+    /** Poll a job until it finishes. Throws JobTimeout on deadline. */
+    async waitForJob(jobId, timeoutSeconds = 300, pollIntervalSeconds = 2) {
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        while (Date.now() < deadline) {
+            const job = await this.job(jobId);
+            if (["success", "failure", "dead"].includes(job.status))
+                return job;
+            await sleep(pollIntervalSeconds * 1000);
+        }
+        throw new JobTimeout(jobId, timeoutSeconds);
+    }
+    // -- browser sandbox ------------------------------------------------------------
+    /** Start a Playwright browser session for no-API automation. */
+    createBrowserSession(targetUrl) {
+        return this.req("POST", "/browser/session", { params: { target_url: targetUrl } });
+    }
+    browserSession(sessionId) {
+        return this.req("GET", `/browser/session/${sessionId}`);
+    }
+    /** Run browser steps (navigate/click/fill/extract/...) synchronously. */
+    browserRun(sessionId, steps) {
+        return this.req("POST", `/browser/session/${sessionId}/run`, { json: { steps } });
+    }
+    /** Queue browser steps as a job. Poll with job()/waitForJob(). */
+    browserRunAsync(sessionId, steps) {
+        return this.req("POST", `/browser/session/${sessionId}/run_async`, { json: { steps } });
+    }
+    // -- approvals ---------------------------------------------------------------
+    approvals(status = "pending", limit = 50, offset = 0) {
+        return this.req("GET", "/tools/approvals", { params: { status, limit, offset } });
+    }
+    /** Decide a pending approval as the requesting user (JWT auth). */
+    approve(approvalId, approved = true) {
+        return this.req("POST", "/tools/approval", { json: { approval_id: approvalId, approved } });
+    }
+    // -- secrets ---------------------------------------------------------------
+    secrets() {
+        return this.req("GET", "/secrets");
+    }
+    setSecret(name, value) {
+        return this.req("PUT", "/secrets", { json: { name, value } });
+    }
+    deleteSecret(name) {
+        return this.req("DELETE", `/secrets/${name}`);
+    }
+    // -- automation ---------------------------------------------------------------
+    triggers() {
+        return this.req("GET", "/triggers");
+    }
+    createTrigger(trigger) {
+        return this.req("POST", "/triggers", { json: trigger });
+    }
+    deleteTrigger(triggerId) {
+        return this.req("DELETE", `/triggers/${triggerId}`);
+    }
+    webhookSubscriptions() {
+        return this.req("GET", "/webhook-subscriptions");
+    }
+    createWebhookSubscription(subscription) {
+        return this.req("POST", "/webhook-subscriptions", { json: subscription });
+    }
+    deleteWebhookSubscription(subscriptionId) {
+        return this.req("DELETE", `/webhook-subscriptions/${subscriptionId}`);
+    }
+    // -- observability ---------------------------------------------------------------
+    executions(opts = {}) {
+        return this.req("GET", "/executions", {
+            params: { action: opts.action, status: opts.status, limit: opts.limit ?? 50, offset: opts.offset ?? 0 },
+        });
+    }
+    audit(opts = {}) {
+        return this.req("GET", "/audit", {
+            params: { action: opts.action, limit: opts.limit ?? 50, offset: opts.offset ?? 0 },
+        });
+    }
+    /** Full audit log as CSV text. */
+    auditExportCsv() {
+        return this.req("GET", "/audit/export", { raw: true });
+    }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "zanii-connect",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Zanii Connect — OAuth connections and tool execution for AI agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "author": "Zanii Agency",
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}