@withloops.ai/contracts 0.3.1 → 0.4.0

package/dist/sync.d.ts

@@ -0,0 +1,338 @@
+import { z } from 'zod';
+import { RecordKind, type SyncManifest } from './manifest.ts';
+/**
+ * Added in 0.4.0 (L2 Sync). The engine core's vocabulary: connector kinds, the CRM of record, external refs, health,
+ * import progress, mapping preview, write-back items, the driver interface both connector kinds implement, and the RPC the
+ * engine adds. Skill devops-loops-developer-platform §2 #1 #4 #5, §3. Only ever ADD.
+ */
+/** `native` = first-party code we build (HubSpot, Salesforce…); `manifest` = a developer app's `sync`, run by the manifest driver. */
+export declare const ConnectorKind: z.ZodEnum<{
+    manifest: "manifest";
+    native: "native";
+}>;
+export type ConnectorKind = z.infer<typeof ConnectorKind>;
+/** `TenantApps.crmConnector` in Vista. Null there = the native Loops CRM is the CRM of record. One per workspace. */
+export declare const CrmConnector: z.ZodObject<{
+    appId: z.ZodString;
+    installId: z.ZodString;
+    kind: z.ZodEnum<{
+        manifest: "manifest";
+        native: "native";
+    }>;
+    setBy: z.ZodString;
+    setAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type CrmConnector = z.infer<typeof CrmConnector>;
+/** A Loops record's identity at the other side (the link table in Vista). */
+export declare const ExternalRef: z.ZodObject<{
+    appId: z.ZodString;
+    installId: z.ZodString;
+    object: z.ZodString;
+    externalId: z.ZodString;
+    lockedFields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    linkedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ExternalRef = z.infer<typeof ExternalRef>;
+/**
+ * `connecting` (no credentials yet) · `needs_auth` (token refused; an admin reconnects) · `importing` (first import running)
+ * · `healthy` · `degraded` (calls failing or rate limited, retrying) · `paused` (auto-pause or an admin paused it).
+ */
+export declare const SyncHealth: z.ZodEnum<{
+    paused: "paused";
+    connecting: "connecting";
+    needs_auth: "needs_auth";
+    importing: "importing";
+    healthy: "healthy";
+    degraded: "degraded";
+}>;
+export type SyncHealth = z.infer<typeof SyncHealth>;
+export declare const ObjectProgress: z.ZodObject<{
+    object: z.ZodString;
+    ours: z.ZodEnum<{
+        CONTACT: "CONTACT";
+        COMPANY: "COMPANY";
+        LEAD: "LEAD";
+        DEAL: "DEAL";
+    }>;
+    enabled: z.ZodBoolean;
+    read: z.ZodNumber;
+    created: z.ZodNumber;
+    matched: z.ZodNumber;
+    failed: z.ZodNumber;
+    total: z.ZodNullable<z.ZodNumber>;
+    lastChangeAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type ObjectProgress = z.infer<typeof ObjectProgress>;
+export declare const ImportState: z.ZodEnum<{
+    failed: "failed";
+    not_started: "not_started";
+    running: "running";
+    done: "done";
+}>;
+export declare const SyncStatus: z.ZodObject<{
+    installId: z.ZodString;
+    appId: z.ZodString;
+    kind: z.ZodEnum<{
+        manifest: "manifest";
+        native: "native";
+    }>;
+    health: z.ZodEnum<{
+        paused: "paused";
+        connecting: "connecting";
+        needs_auth: "needs_auth";
+        importing: "importing";
+        healthy: "healthy";
+        degraded: "degraded";
+    }>;
+    import: z.ZodObject<{
+        state: z.ZodEnum<{
+            failed: "failed";
+            not_started: "not_started";
+            running: "running";
+            done: "done";
+        }>;
+        runId: z.ZodNullable<z.ZodString>;
+        startedAt: z.ZodNullable<z.ZodISODateTime>;
+        finishedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>;
+    objects: z.ZodArray<z.ZodObject<{
+        object: z.ZodString;
+        ours: z.ZodEnum<{
+            CONTACT: "CONTACT";
+            COMPANY: "COMPANY";
+            LEAD: "LEAD";
+            DEAL: "DEAL";
+        }>;
+        enabled: z.ZodBoolean;
+        read: z.ZodNumber;
+        created: z.ZodNumber;
+        matched: z.ZodNumber;
+        failed: z.ZodNumber;
+        total: z.ZodNullable<z.ZodNumber>;
+        lastChangeAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+    changes: z.ZodObject<{
+        inLastHour: z.ZodNumber;
+        outLastHour: z.ZodNumber;
+        echoesDropped: z.ZodNumber;
+        deadLettered: z.ZodNumber;
+    }, z.core.$strip>;
+    lastError: z.ZodNullable<z.ZodObject<{
+        at: z.ZodISODateTime;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+    nextPollAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type SyncStatus = z.infer<typeof SyncStatus>;
+/** A few of their records shown beside what Loops would make of them, before the first import. */
+export declare const MappingPreview: z.ZodObject<{
+    object: z.ZodString;
+    ours: z.ZodEnum<{
+        CONTACT: "CONTACT";
+        COMPANY: "COMPANY";
+        LEAD: "LEAD";
+        DEAL: "DEAL";
+    }>;
+    fields: z.ZodArray<z.ZodObject<{
+        theirs: z.ZodString;
+        ours: z.ZodString;
+        owner: z.ZodEnum<{
+            theirs: "theirs";
+            ours: "ours";
+        }>;
+    }, z.core.$strip>>;
+    rows: z.ZodArray<z.ZodObject<{
+        externalId: z.ZodString;
+        values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        links: z.ZodArray<z.ZodObject<{
+            to: z.ZodEnum<{
+                CONTACT: "CONTACT";
+                COMPANY: "COMPANY";
+                LEAD: "LEAD";
+                DEAL: "DEAL";
+            }>;
+            role: z.ZodNullable<z.ZodString>;
+            externalIds: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MappingPreview = z.infer<typeof MappingPreview>;
+/** What the admin picked in the bring-your-own-CRM setup. */
+export declare const SyncSettings: z.ZodObject<{
+    objects: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    crmOfRecord: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SyncSettings = z.infer<typeof SyncSettings>;
+/** One thing Loops owns, written to their timeline. `{{item.*}}` in a write-back body template. */
+export declare const WriteBackItem: z.ZodObject<{
+    kind: z.ZodEnum<{
+        call: "call";
+        transcript: "transcript";
+        meeting: "meeting";
+        note: "note";
+        action: "action";
+        campaignReply: "campaignReply";
+    }>;
+    loopsId: z.ZodString;
+    title: z.ZodString;
+    text: z.ZodString;
+    markdown: z.ZodNullable<z.ZodString>;
+    occurredAt: z.ZodISODateTime;
+    durationSeconds: z.ZodNullable<z.ZodNumber>;
+    direction: z.ZodNullable<z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>>;
+    url: z.ZodNullable<z.ZodString>;
+    byEmail: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type WriteBackItem = z.infer<typeof WriteBackItem>;
+/**
+ * Names a body template may use. In paths only `{id}` and `{object}`.
+ * - list body: `{{limit}}`, `{{offset}}`, `{{page}}`, `{{cursor}}`, `{{updatedSince}}`
+ * - create / update body: `{{ours.<field>}}` (a Loops field from the object's map), `{{record.id}}`
+ * - write-back body: `{{item.<field>}}` (WriteBackItem), `{{record.id}}`, `{{record.object}}`
+ * - webhook register body: `{{hookUrl}}`, `{{object}}`
+ */
+export declare const TEMPLATE_VARIABLES: {
+    readonly list: readonly ["limit", "offset", "page", "cursor", "updatedSince"];
+    readonly record: readonly ["ours.*", "record.id"];
+    readonly writeBack: readonly ["item.*", "record.id", "record.object"];
+    readonly register: readonly ["hookUrl", "object"];
+};
+/** One of their records, already mapped to Loops field names (ownership is the core's job, not the driver's). */
+export interface ExternalRecord {
+    object: string;
+    externalId: string;
+    updatedAt: string | null;
+    /** Loops field → value, every mapped field present (null when empty). */
+    values: Record<string, unknown>;
+    links: {
+        to: RecordKind;
+        role: string | null;
+        externalIds: string[];
+    }[];
+    /** SHA-256 of the mapped values (sorted keys): the echo guard and full-mode polling compare this. */
+    hash: string;
+}
+export interface ListPage {
+    records: ExternalRecord[];
+    /** Opaque; pass back for the next page. Null on the last page. */
+    next: string | null;
+    /** Their total when the API says it. */
+    total: number | null;
+}
+/** A change their webhook announced. `record` is filled when the driver could read it (created/updated). */
+export interface HookChange {
+    type: 'created' | 'updated' | 'deleted';
+    object: string;
+    externalId: string;
+    record: ExternalRecord | null;
+}
+/**
+ * The only door a driver has to their API. The core adds the base URL, the credentials (from the vault, refreshed when
+ * expired), the rate limit and `Retry-After`; it answers 401/403 by marking the install `needs_auth`. A driver never sees a secret.
+ */
+export interface ConnectorHttp {
+    request(method: string, path: string, init?: {
+        query?: Record<string, string>;
+        body?: unknown;
+    }): Promise<{
+        status: number;
+        headers: Headers;
+        json: unknown;
+    }>;
+}
+export interface ConnectorDriver {
+    readonly kind: ConnectorKind;
+    /** Their objects this connector syncs, in import order (companies before the people who link to them). */
+    objects(): {
+        object: string;
+        ours: RecordKind;
+        fields: {
+            theirs: string;
+            ours: string;
+            owner: 'theirs' | 'ours';
+        }[];
+        match: string[];
+    }[];
+    test(http: ConnectorHttp): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    list(http: ConnectorHttp, object: string, page: {
+        next: string | null;
+        updatedSince: string | null;
+    }): Promise<ListPage>;
+    get(http: ConnectorHttp, object: string, externalId: string): Promise<ExternalRecord | null>;
+    /** Null when the connector cannot create this object. */
+    create(http: ConnectorHttp, object: string, values: Record<string, unknown>): Promise<{
+        externalId: string;
+    } | null>;
+    /** `values` holds only Loops-owned fields. False when the connector cannot update this object. */
+    update(http: ConnectorHttp, object: string, externalId: string, values: Record<string, unknown>): Promise<boolean>;
+    /** Null when the connector does not declare this kind. */
+    writeBack(http: ConnectorHttp, target: {
+        object: string;
+        externalId: string;
+    }, item: WriteBackItem): Promise<{
+        externalId: string | null;
+    } | null>;
+    verifyHook(rawBody: string, headers: Headers, secret: string): Promise<boolean>;
+    /** After verifyHook. Reads created/updated records with `get`. */
+    parseHook(http: ConnectorHttp, rawBody: string): Promise<HookChange[]>;
+    /** Null when the connector does not register webhooks itself. */
+    registerHook(http: ConnectorHttp, hookUrl: string): Promise<{
+        hookId: string | null;
+        secret: string;
+    } | null>;
+    unregisterHook(http: ConnectorHttp, hookId: string): Promise<void>;
+}
+/** The manifest driver's constructor (`@withloops.ai/contracts/connector`). */
+export type CreateManifestDriver = (sync: SyncManifest) => ConnectorDriver;
+export declare const SyncCaller: z.ZodObject<{
+    workspaceId: z.ZodString;
+    userId: z.ZodString;
+}, z.core.$strip>;
+/** `backend-apps-engine` default WorkerEntrypoint implements this as well as EngineRpc + EngineVaultRpc. */
+export interface EngineSyncRpc {
+    syncStatus(installId: string): Promise<SyncStatus | null>;
+    /** Save the admin's picks; starts nothing. */
+    configureSync(installId: string, settings: SyncSettings): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    previewMapping(installId: string, object: string, limit?: number): Promise<{
+        ok: true;
+        preview: MappingPreview;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** Starts the first import as a Workflow (resumable). Safe to call twice: a running import is returned, not restarted. */
+    startImport(installId: string): Promise<{
+        ok: true;
+        runId: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    pauseSync(installId: string, paused: boolean): Promise<{
+        ok: true;
+    }>;
+    /** Loops wrote something it owns (call, note…) on a record linked to this install; queued, written to their timeline. */
+    writeBack(installId: string, record: {
+        kind: z.infer<typeof RecordKind>;
+        loopsId: string;
+    }, item: WriteBackItem): Promise<{
+        ok: true;
+        queued: true;
+    }>;
+    /** Check the credentials with the connector's test call. */
+    testConnection(installId: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+}

package/dist/sync.js

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import { AppId, InstallId, Timestamp, UserId, WorkspaceId } from "./ids.js";
+import { RecordKind, WriteBackKind } from "./manifest.js";
+/**
+ * Added in 0.4.0 (L2 Sync). The engine core's vocabulary: connector kinds, the CRM of record, external refs, health,
+ * import progress, mapping preview, write-back items, the driver interface both connector kinds implement, and the RPC the
+ * engine adds. Skill devops-loops-developer-platform §2 #1 #4 #5, §3. Only ever ADD.
+ */
+// ── Connector kinds and the CRM of record ───────────────────────────────────────
+/** `native` = first-party code we build (HubSpot, Salesforce…); `manifest` = a developer app's `sync`, run by the manifest driver. */
+export const ConnectorKind = z.enum(['native', 'manifest']);
+/** `TenantApps.crmConnector` in Vista. Null there = the native Loops CRM is the CRM of record. One per workspace. */
+export const CrmConnector = z.object({
+    appId: AppId,
+    installId: InstallId,
+    kind: ConnectorKind,
+    setBy: UserId,
+    setAt: Timestamp,
+});
+/** A Loops record's identity at the other side (the link table in Vista). */
+export const ExternalRef = z.object({
+    appId: AppId,
+    installId: InstallId,
+    /** Their object name (`people`). */
+    object: z.string().min(1),
+    externalId: z.string().min(1).max(200),
+    /** Loops fields their CRM owns on this record: locked in Loops ("Edited in Attio"). */
+    lockedFields: z.array(z.string()).default([]),
+    linkedAt: Timestamp,
+});
+// ── Health, import, preview ─────────────────────────────────────────────────────
+/**
+ * `connecting` (no credentials yet) · `needs_auth` (token refused; an admin reconnects) · `importing` (first import running)
+ * · `healthy` · `degraded` (calls failing or rate limited, retrying) · `paused` (auto-pause or an admin paused it).
+ */
+export const SyncHealth = z.enum(['connecting', 'needs_auth', 'importing', 'healthy', 'degraded', 'paused']);
+export const ObjectProgress = z.object({
+    object: z.string(),
+    ours: RecordKind,
+    enabled: z.boolean(),
+    /** Records read from their side in the first import. */
+    read: z.number().int().min(0),
+    created: z.number().int().min(0),
+    matched: z.number().int().min(0),
+    failed: z.number().int().min(0),
+    /** Their total when their API says it; null otherwise. */
+    total: z.number().int().min(0).nullable(),
+    lastChangeAt: Timestamp.nullable(),
+});
+export const ImportState = z.enum(['not_started', 'running', 'done', 'failed']);
+export const SyncStatus = z.object({
+    installId: InstallId,
+    appId: AppId,
+    kind: ConnectorKind,
+    health: SyncHealth,
+    import: z.object({
+        state: ImportState,
+        runId: z.string().nullable(),
+        startedAt: Timestamp.nullable(),
+        finishedAt: Timestamp.nullable(),
+    }),
+    objects: z.array(ObjectProgress),
+    changes: z.object({
+        inLastHour: z.number().int().min(0),
+        outLastHour: z.number().int().min(0),
+        echoesDropped: z.number().int().min(0),
+        deadLettered: z.number().int().min(0),
+    }),
+    /** Plain words, the last problem only. Never a secret, never a stack trace. */
+    lastError: z.object({ at: Timestamp, message: z.string() }).nullable(),
+    nextPollAt: Timestamp.nullable(),
+});
+/** A few of their records shown beside what Loops would make of them, before the first import. */
+export const MappingPreview = z.object({
+    object: z.string(),
+    ours: RecordKind,
+    fields: z.array(z.object({ theirs: z.string(), ours: z.string(), owner: z.enum(['theirs', 'ours']) })),
+    rows: z.array(z.object({
+        externalId: z.string(),
+        values: z.record(z.string(), z.unknown()),
+        links: z.array(z.object({ to: RecordKind, role: z.string().nullable(), externalIds: z.array(z.string()) })),
+    })),
+});
+/** What the admin picked in the bring-your-own-CRM setup. */
+export const SyncSettings = z.object({
+    /** Their object names to sync; every object in the manifest when empty. */
+    objects: z.array(z.string()).default([]),
+    /** Make this install the workspace's CRM of record (`TenantApps.crmConnector`). */
+    crmOfRecord: z.boolean().default(false),
+});
+// ── Write-back ──────────────────────────────────────────────────────────────────
+/** One thing Loops owns, written to their timeline. `{{item.*}}` in a write-back body template. */
+export const WriteBackItem = z.object({
+    kind: WriteBackKind,
+    /** Loops id of the thing (call, note…), for the echo guard and to find it again. */
+    loopsId: z.string(),
+    title: z.string().max(300),
+    /** Plain text. */
+    text: z.string().max(100_000),
+    markdown: z.string().max(100_000).nullable(),
+    occurredAt: Timestamp,
+    durationSeconds: z.number().int().min(0).nullable(),
+    direction: z.enum(['inbound', 'outbound']).nullable(),
+    /** Link back to the item in Loops. */
+    url: z.string().nullable(),
+    byEmail: z.string().nullable(),
+});
+// ── Template variables (manifest BodyTemplate) ──────────────────────────────────
+/**
+ * Names a body template may use. In paths only `{id}` and `{object}`.
+ * - list body: `{{limit}}`, `{{offset}}`, `{{page}}`, `{{cursor}}`, `{{updatedSince}}`
+ * - create / update body: `{{ours.<field>}}` (a Loops field from the object's map), `{{record.id}}`
+ * - write-back body: `{{item.<field>}}` (WriteBackItem), `{{record.id}}`, `{{record.object}}`
+ * - webhook register body: `{{hookUrl}}`, `{{object}}`
+ */
+export const TEMPLATE_VARIABLES = {
+    list: ['limit', 'offset', 'page', 'cursor', 'updatedSince'],
+    record: ['ours.*', 'record.id'],
+    writeBack: ['item.*', 'record.id', 'record.object'],
+    register: ['hookUrl', 'object'],
+};
+// ── Engine RPC added in L2 ──────────────────────────────────────────────────────
+export const SyncCaller = z.object({ workspaceId: WorkspaceId, userId: UserId });

package/dist/trust.d.ts

@@ -136,9 +136,9 @@ export declare function appClientSecretRef(appId: string, ownerWorkspaceId: stri
 /** Engine-side code exchange for an app connecting OUT (the handoff at api.thesoogroup.com/oauth/callback). Added in 0.3.1. */
 export declare const OAuthCodeExchange: z.ZodObject<{
     install: z.ZodObject<{
+        appId: z.ZodString;
         workspaceId: z.ZodString;
         installId: z.ZodString;
-        appId: z.ZodString;
     }, z.core.$strip>;
     ownerWorkspaceId: z.ZodString;
     tokenUrl: z.ZodString;

package/examples/attio-sync.manifest.json

@@ -0,0 +1,146 @@
+{
+  "manifestVersion": 1,
+  "id": "attio-sync",
+  "name": "Attio sync",
+  "version": "0.1.0",
+  "summary": "Use Attio as your CRM of record: people and companies come into Loops, calls and notes go to their Attio timeline.",
+  "developer": { "name": "Loops developer platform proof", "email": "developers@withloops.ai", "website": "https://withloops.ai" },
+  "visibility": "private",
+  "scopes": ["contacts:write", "companies:write"],
+  "sync": {
+    "baseUrl": "https://api.attio.com",
+    "auth": {
+      "type": "apiKey",
+      "header": "Authorization",
+      "prefix": "Bearer ",
+      "label": "Attio access token",
+      "helpUrl": "https://attio.com/help/apps/other-apps/generating-an-api-key"
+    },
+    "test": { "method": "GET", "path": "/v2/self" },
+    "objects": [
+      {
+        "theirs": "companies",
+        "ours": "COMPANY",
+        "idPath": "id.record_id",
+        "list": {
+          "path": "/v2/objects/companies/records/query",
+          "method": "POST",
+          "itemsPath": "data",
+          "body": { "limit": "{{limit}}", "offset": "{{offset}}" },
+          "paging": { "style": "offset", "param": "offset", "sizeParam": "limit", "size": 100, "in": "body" }
+        },
+        "get": { "method": "GET", "path": "/v2/objects/companies/records/{id}", "itemPath": "data" },
+        "create": {
+          "method": "POST",
+          "path": "/v2/objects/companies/records",
+          "itemPath": "data",
+          "body": { "data": { "values": { "name": "{{ours.name}}", "domains": ["{{ours.domain}}"] } } }
+        },
+        "fields": [
+          { "theirs": "values.name[0].value", "ours": "name", "owner": "theirs", "transform": ["trim"] },
+          { "theirs": "values.domains[0].domain", "ours": "domain", "owner": "theirs", "transform": ["lower"] }
+        ],
+        "match": ["domain"]
+      },
+      {
+        "theirs": "people",
+        "ours": "CONTACT",
+        "idPath": "id.record_id",
+        "list": {
+          "path": "/v2/objects/people/records/query",
+          "method": "POST",
+          "itemsPath": "data",
+          "body": { "limit": "{{limit}}", "offset": "{{offset}}" },
+          "paging": { "style": "offset", "param": "offset", "sizeParam": "limit", "size": 100, "in": "body" }
+        },
+        "get": { "method": "GET", "path": "/v2/objects/people/records/{id}", "itemPath": "data" },
+        "create": {
+          "method": "POST",
+          "path": "/v2/objects/people/records",
+          "itemPath": "data",
+          "body": {
+            "data": {
+              "values": {
+                "name": { "first_name": "{{ours.firstName}}", "last_name": "{{ours.lastName}}", "full_name": "{{ours.firstName}} {{ours.lastName}}" },
+                "email_addresses": ["{{ours.email}}"],
+                "job_title": "{{ours.jobTitle}}"
+              }
+            }
+          }
+        },
+        "fields": [
+          { "theirs": "values.name[0].first_name", "ours": "firstName", "owner": "theirs", "transform": ["trim"] },
+          { "theirs": "values.name[0].last_name", "ours": "lastName", "owner": "theirs", "transform": ["trim"] },
+          { "theirs": "values.email_addresses[0].email_address", "ours": "email", "owner": "theirs", "transform": ["lower"] },
+          { "theirs": "values.phone_numbers[0].original_phone_number", "ours": "phone", "owner": "theirs" },
+          { "theirs": "values.job_title[0].value", "ours": "jobTitle", "owner": "theirs" }
+        ],
+        "match": ["email"]
+      }
+    ],
+    "links": [
+      { "from": "CONTACT", "to": "COMPANY", "theirs": "values.company[0].target_record_id", "role": "employee" }
+    ],
+    "changeFeed": {
+      "webhook": {
+        "signature": { "scheme": "hmac-sha256", "header": "Attio-Signature", "encoding": "hex" },
+        "eventsPath": "events",
+        "typePath": "event_type",
+        "idPath": "id.record_id",
+        "objectPath": "id.object_id",
+        "types": { "created": ["record.created"], "updated": ["record.updated"], "deleted": ["record.deleted"] },
+        "register": {
+          "call": {
+            "method": "POST",
+            "path": "/v2/webhooks",
+            "body": {
+              "data": {
+                "target_url": "{{hookUrl}}",
+                "subscriptions": [
+                  { "event_type": "record.created", "filter": null },
+                  { "event_type": "record.updated", "filter": null },
+                  { "event_type": "record.deleted", "filter": null }
+                ]
+              }
+            }
+          },
+          "secretPath": "data.secret",
+          "idPath": "data.id.webhook_id",
+          "unregister": { "method": "DELETE", "path": "/v2/webhooks/{id}" }
+        }
+      },
+      "polling": { "everyMinutes": 60, "mode": "full" }
+    },
+    "writeBack": {
+      "note": {
+        "method": "POST",
+        "path": "/v2/notes",
+        "idPath": "data.id.note_id",
+        "body": {
+          "data": {
+            "parent_object": "{{record.object}}",
+            "parent_record_id": "{{record.id}}",
+            "title": "{{item.title}}",
+            "format": "markdown",
+            "content": "{{item.text}}"
+          }
+        }
+      },
+      "call": {
+        "method": "POST",
+        "path": "/v2/notes",
+        "idPath": "data.id.note_id",
+        "body": {
+          "data": {
+            "parent_object": "{{record.object}}",
+            "parent_record_id": "{{record.id}}",
+            "title": "{{item.title}}",
+            "format": "plaintext",
+            "content": "{{item.text}}"
+          }
+        }
+      }
+    },
+    "limits": { "requestsPerSecond": 20, "burst": 25, "retryAfterHeader": "Retry-After" }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withloops.ai/contracts",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "The Loops developer platform contracts (zod): app manifest v1, scopes, events, the /v1 API envelope and registry records. Everything else builds on these.",
   "type": "module",
   "license": "UNLICENSED",