@fayz-ai/sdk 0.10.1 → 0.12.0

package/README.md

@@ -9,7 +9,7 @@
 
 Fayz builds real, multi-tenant SaaS apps by composing plugins. `@fayz-ai/sdk` is the seam between a generated Fayz project and the platform behind it: a typed API client, the shared manifest/user/params types, a runtime broker for OAuth-backed integrations, and the release-channel resolver that keeps every package on a coherent version set.
 
-This is the lowest-trust, zero-React layer — no UI, no framework, just the contract. Generated apps call Fayz through the SDK instead of importing provider clients directly, so OAuth secrets and tenant authority stay server-side where they belong. If you're reading Fayz tables, exchanging plugin OAuth grants, or pinning a package channel, you start here.
+This is the lowest-trust, zero-React layer — no UI, no framework, just the contract. Generated apps call Fayz through the SDK instead of importing provider clients directly, which is what keeps OAuth secrets and tenant authority server-side. If you're reading Fayz tables, exchanging plugin OAuth grants, or pinning a package channel, you start here.
 
 ## What's inside
 - `createFayzClient` / `fayz` — typed client with `auth.me()` and `data` row access (`listRows`, `countRows`, `createRow`, `updateRow`, `deleteRows`) plus `FayzApiError`

package/dist/automations.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Client for the Fayz public automations surface.
+ *
+ * `/api/public/projects/:id/automations` is how a published app reads and
+ * manages the automations the PLATFORM executes for it — the same rows the
+ * owner sees in Fayz > Automations. Reads authenticate with the publishable
+ * key alone; writes additionally carry the signed-in end user's app session
+ * token (Supabase access token), verified server-side against the app's own
+ * JWKS — a bundle-shipped key must never be enough to flip a tenant's switch.
+ */
+export interface FayzAutomationAction {
+    id: string;
+    type: string;
+    enabled: boolean;
+    config: {
+        subject?: string;
+        body?: string;
+        recipient?: string;
+    };
+}
+export interface FayzAutomation {
+    id: string;
+    name: string;
+    trigger: string;
+    triggerConfig: {
+        eventKey?: string;
+        sourceChannel?: string;
+        conditions?: unknown[];
+        conditionMatch?: string;
+    };
+    enabled: boolean;
+    tenantId: string | null;
+    actions: FayzAutomationAction[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface FayzAutomationExecution {
+    id: string;
+    automationId: string;
+    automationName: string;
+    trigger: string;
+    status: string;
+    error: string | null;
+    executedAt: string;
+    tenantId: string | null;
+}
+export interface FayzAutomationsClientOptions {
+    /** e.g. `https://fayz.ai/api` — the same base the agent client takes. */
+    baseUrl: string;
+    projectId: string;
+    publishableKey: string;
+    fetcher?: typeof fetch;
+}
+export declare class FayzAutomationsError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export interface FayzAutomationsClient {
+    list(input: {
+        tenantId: string;
+    }): Promise<FayzAutomation[]>;
+    create(input: {
+        tenantId: string;
+        appSessionToken: string;
+        eventKey: string;
+        sourceChannel: string;
+        name?: string;
+        enabled?: boolean;
+        action?: {
+            subject?: string;
+            body?: string;
+            recipient?: string;
+        };
+    }): Promise<FayzAutomation>;
+    update(input: {
+        id: string;
+        tenantId: string;
+        appSessionToken: string;
+        enabled?: boolean;
+        /** `null` clears a field — the app re-materializes its catalog default. */
+        action?: {
+            subject?: string | null;
+            body?: string | null;
+            recipient?: string | null;
+        };
+    }): Promise<FayzAutomation>;
+    listExecutions(input: {
+        tenantId: string;
+        eventKey?: string;
+        limit?: number;
+    }): Promise<FayzAutomationExecution[]>;
+}
+export declare function createFayzAutomationsClient(options: FayzAutomationsClientOptions): FayzAutomationsClient;
+//# sourceMappingURL=automations.d.ts.map

package/dist/automations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automations.d.ts","sourceRoot":"","sources":["../src/automations.ts"],"names":[],"mappings":"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"}

package/dist/automations.js

@@ -0,0 +1,61 @@
+// src/automations.ts
+var FayzAutomationsError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+};
+function createFayzAutomationsClient(options) {
+  const fetcher = options.fetcher ?? ((...args) => fetch(...args));
+  const base = `${options.baseUrl.replace(/\/$/, "")}/public/projects/${options.projectId}/automations`;
+  async function call(path, init = {}) {
+    const { appSessionToken, ...rest } = init;
+    const response = await fetcher(`${base}${path}`, {
+      ...rest,
+      headers: {
+        "Content-Type": "application/json",
+        "x-fayz-agent-key": options.publishableKey,
+        ...appSessionToken ? { Authorization: `Bearer ${appSessionToken}` } : {},
+        ...rest.headers ?? {}
+      }
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw new FayzAutomationsError(body.message ?? body.error ?? `HTTP ${response.status}`, response.status);
+    }
+    return body;
+  }
+  return {
+    async list({ tenantId }) {
+      const body = await call(
+        `?tenantId=${encodeURIComponent(tenantId)}`
+      );
+      return body.automations ?? [];
+    },
+    async create({ tenantId, appSessionToken, ...rest }) {
+      const body = await call(
+        `?tenantId=${encodeURIComponent(tenantId)}`,
+        { method: "POST", body: JSON.stringify(rest), appSessionToken }
+      );
+      return body.automation;
+    },
+    async update({ id, tenantId, appSessionToken, ...rest }) {
+      const body = await call(
+        `/${encodeURIComponent(id)}?tenantId=${encodeURIComponent(tenantId)}`,
+        { method: "PATCH", body: JSON.stringify(rest), appSessionToken }
+      );
+      return body.automation;
+    },
+    async listExecutions({ tenantId, eventKey, limit }) {
+      const params = new URLSearchParams({ tenantId });
+      if (eventKey) params.set("eventKey", eventKey);
+      if (limit) params.set("limit", String(limit));
+      const body = await call(`/executions?${params}`);
+      return body.executions ?? [];
+    }
+  };
+}
+
+export { FayzAutomationsError, createFayzAutomationsClient };
+//# sourceMappingURL=automations.js.map
+//# sourceMappingURL=automations.js.map

package/dist/automations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/automations.ts"],"names":[],"mappings":"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","file":"automations.js","sourcesContent":["/**\n * Client for the Fayz public automations surface.\n *\n * `/api/public/projects/:id/automations` is how a published app reads and\n * manages the automations the PLATFORM executes for it — the same rows the\n * owner sees in Fayz > Automations. Reads authenticate with the publishable\n * key alone; writes additionally carry the signed-in end user's app session\n * token (Supabase access token), verified server-side against the app's own\n * JWKS — a bundle-shipped key must never be enough to flip a tenant's switch.\n */\n\nexport interface FayzAutomationAction {\n  id: string\n  type: string\n  enabled: boolean\n  config: { subject?: string; body?: string; recipient?: string }\n}\n\nexport interface FayzAutomation {\n  id: string\n  name: string\n  trigger: string\n  triggerConfig: {\n    eventKey?: string\n    sourceChannel?: string\n    conditions?: unknown[]\n    conditionMatch?: string\n  }\n  enabled: boolean\n  tenantId: string | null\n  actions: FayzAutomationAction[]\n  createdAt: string\n  updatedAt: string\n}\n\nexport interface FayzAutomationExecution {\n  id: string\n  automationId: string\n  automationName: string\n  trigger: string\n  status: string\n  error: string | null\n  executedAt: string\n  tenantId: string | null\n}\n\nexport interface FayzAutomationsClientOptions {\n  /** e.g. `https://fayz.ai/api` — the same base the agent client takes. */\n  baseUrl: string\n  projectId: string\n  publishableKey: string\n  fetcher?: typeof fetch\n}\n\nexport class FayzAutomationsError extends Error {\n  constructor(message: string, readonly status: number) {\n    super(message)\n  }\n}\n\nexport interface FayzAutomationsClient {\n  list(input: { tenantId: string }): Promise<FayzAutomation[]>\n  create(input: {\n    tenantId: string\n    appSessionToken: string\n    eventKey: string\n    sourceChannel: string\n    name?: string\n    enabled?: boolean\n    action?: { subject?: string; body?: string; recipient?: string }\n  }): Promise<FayzAutomation>\n  update(input: {\n    id: string\n    tenantId: string\n    appSessionToken: string\n    enabled?: boolean\n    /** `null` clears a field — the app re-materializes its catalog default. */\n    action?: { subject?: string | null; body?: string | null; recipient?: string | null }\n  }): Promise<FayzAutomation>\n  listExecutions(input: {\n    tenantId: string\n    eventKey?: string\n    limit?: number\n  }): Promise<FayzAutomationExecution[]>\n}\n\nexport function createFayzAutomationsClient(options: FayzAutomationsClientOptions): FayzAutomationsClient {\n  const fetcher = options.fetcher ?? ((...args: Parameters<typeof fetch>) => fetch(...args))\n  const base = `${options.baseUrl.replace(/\\/$/, '')}/public/projects/${options.projectId}/automations`\n\n  async function call<T>(\n    path: string,\n    init: RequestInit & { appSessionToken?: string } = {},\n  ): Promise<T> {\n    const { appSessionToken, ...rest } = init\n    const response = await fetcher(`${base}${path}`, {\n      ...rest,\n      headers: {\n        'Content-Type': 'application/json',\n        'x-fayz-agent-key': options.publishableKey,\n        ...(appSessionToken ? { Authorization: `Bearer ${appSessionToken}` } : {}),\n        ...(rest.headers ?? {}),\n      },\n    })\n    const body = (await response.json().catch(() => ({}))) as T & { message?: string; error?: string }\n    if (!response.ok) {\n      throw new FayzAutomationsError(body.message ?? body.error ?? `HTTP ${response.status}`, response.status)\n    }\n    return body\n  }\n\n  return {\n    async list({ tenantId }) {\n      const body = await call<{ automations: FayzAutomation[] }>(\n        `?tenantId=${encodeURIComponent(tenantId)}`,\n      )\n      return body.automations ?? []\n    },\n\n    async create({ tenantId, appSessionToken, ...rest }) {\n      const body = await call<{ automation: FayzAutomation }>(\n        `?tenantId=${encodeURIComponent(tenantId)}`,\n        { method: 'POST', body: JSON.stringify(rest), appSessionToken },\n      )\n      return body.automation\n    },\n\n    async update({ id, tenantId, appSessionToken, ...rest }) {\n      const body = await call<{ automation: FayzAutomation }>(\n        `/${encodeURIComponent(id)}?tenantId=${encodeURIComponent(tenantId)}`,\n        { method: 'PATCH', body: JSON.stringify(rest), appSessionToken },\n      )\n      return body.automation\n    },\n\n    async listExecutions({ tenantId, eventKey, limit }) {\n      const params = new URLSearchParams({ tenantId })\n      if (eventKey) params.set('eventKey', eventKey)\n      if (limit) params.set('limit', String(limit))\n      const body = await call<{ executions: FayzAutomationExecution[] }>(`/executions?${params}`)\n      return body.executions ?? []\n    },\n  }\n}\n"]}