@withloops.ai/contracts 0.3.1 → 0.4.0

package/dist/manifest.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { AppId, HttpsUrl, SemVer } from "./ids.js";
 import { EventTypeSchema, scopeForEvent } from "./events.js";
 import { ScopeSchema, expandScopes } from "./scopes.js";
+import { LOOPS_FIELD_NAMES } from "./fields.js";
 /**
  * App manifest v1 (`loops.manifest.json`). Everything is a Loops App: one manifest, two optional halves —
  * `sync` (declarative CRM connector, run by the one Loops sync engine) and `ui` (LoopKit). Skill §2 #1–#3, §3.
@@ -22,6 +23,45 @@ const RECORD_SCOPE = {
     loop: { read: 'loops:read', write: 'loops:write' },
 };
 const PathTemplate = z.string().regex(/^\/[A-Za-z0-9_\-./{}:]*$/, 'A path starting with /, e.g. /crm/v3/objects/contacts');
+/**
+ * Added in 0.4.0 (L2). A JSON body template. A string that is exactly `{{name}}` takes the value as it is (type kept);
+ * `{{name}}` inside longer text is written as text. A key whose value comes out null or missing is left out, so is a null
+ * array item and an object left empty. Names: see `TEMPLATE_VARIABLES` in sync.ts. Pure: no code, no loops, no conditions.
+ */
+export const BodyTemplate = z.json();
+/** Added in 0.4.0. A dotted path into a JSON answer: `data`, `values.name[0].first_name`, `values.associated_people[*].target_record_id`. */
+export const JsonPath = z.string().regex(/^[A-Za-z0-9_$-]+(\[(\d+|\*)\])?(\.[A-Za-z0-9_$-]+(\[(\d+|\*)\])?)*$/, 'A dotted path like data.items or values.name[0].first_name');
+/** Added in 0.4.0. Small pure value transforms, applied in order when reading their value. */
+export const ValueTransform = z.enum(['trim', 'lower', 'upper', 'string', 'number', 'boolean', 'isoDate', 'first', 'domainFromUrl']);
+/** Added in 0.4.0. How a list call pages. `cursor`: their answer holds the next cursor; `offset`/`page`: count up until a short page. */
+export const Paging = z.discriminatedUnion('style', [
+    z.object({ style: z.literal('cursor'), param: z.string().min(1), nextPath: JsonPath, in: z.enum(['query', 'body']).default('query') }),
+    z.object({
+        style: z.literal('offset'),
+        param: z.string().min(1),
+        sizeParam: z.string().min(1),
+        size: z.number().int().min(1).max(1000).default(100),
+        in: z.enum(['query', 'body']).default('query'),
+    }),
+    z.object({
+        style: z.literal('page'),
+        param: z.string().min(1),
+        sizeParam: z.string().min(1),
+        size: z.number().int().min(1).max(1000).default(100),
+        startAt: z.number().int().min(0).max(1).default(1),
+        in: z.enum(['query', 'body']).default('query'),
+    }),
+]);
+/** Added in 0.4.0. One HTTP call against their API. `{id}` in the path is their record id. */
+export const RecordCall = z.object({
+    method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).default('GET'),
+    path: PathTemplate,
+    body: BodyTemplate.optional(),
+    /** Where the record sits in the answer (`data`); the whole answer when left out. */
+    itemPath: JsonPath.optional(),
+    /** Where their id sits in the answer of a create (`data.id.record_id`); defaults to the object's idPath under itemPath. */
+    idPath: JsonPath.optional(),
+});
 // ── sync: the connector half ────────────────────────────────────────────────────
 export const SyncAuth = z.discriminatedUnion('type', [
     z.object({
@@ -37,14 +77,21 @@ export const SyncAuth = z.discriminatedUnion('type', [
         type: z.literal('apiKey'),
         header: z.string().min(1).default('Authorization'),
         prefix: z.string().optional(),
+        /** Added in 0.4.0. What the admin is asked for at install ("Attio access token"), and where to find it. */
+        label: z.string().min(1).max(80).optional(),
+        helpUrl: HttpsUrl.optional(),
     }),
 ]);
 /** Who owns a field. The customer's CRM owns its fields (locked in Loops); Loops owns its own. Owner wins, never last-write-wins. */
 export const FieldOwner = z.enum(['theirs', 'ours']);
 export const SyncField = z.object({
+    /** Where the value sits in their record: a field name or a JsonPath (`values.email_addresses[0].email_address`). */
     theirs: z.string().min(1),
+    /** The Loops field (`LOOPS_FIELDS` in sync.ts) or `custom.<key>` for a custom field. */
     ours: z.string().min(1),
     owner: FieldOwner,
+    /** Added in 0.4.0. Applied in order to their value when reading it. */
+    transform: z.array(ValueTransform).optional(),
 });
 export const SyncObject = z.object({
     theirs: z.string().min(1),
@@ -55,30 +102,95 @@ export const SyncObject = z.object({
         cursorParam: z.string().optional(),
         nextCursorPath: z.string().optional(),
         updatedSinceParam: z.string().optional(),
+        /** Added in 0.4.0. GET by default; POST for APIs that query with a body. */
+        method: z.enum(['GET', 'POST']).optional(),
+        /** Added in 0.4.0. Body for a POST list (`{{limit}}`, `{{offset}}`, `{{cursor}}`, `{{updatedSince}}` fill in). */
+        body: BodyTemplate.optional(),
+        /** Added in 0.4.0. Replaces cursorParam/nextCursorPath when set. */
+        paging: Paging.optional(),
     }),
     fields: z.array(SyncField).min(1),
     /** Dedupe keys, in order: e.g. ["email"] for contacts, ["domain"] for companies. External id always matches first. */
     match: z.array(z.string().min(1)).default([]),
+    /** Added in 0.4.0. Where their id sits in one item (default `id`). */
+    idPath: JsonPath.optional(),
+    /** Added in 0.4.0. Where their last-changed time sits; without it, polling compares each record with what it saw last. */
+    updatedAtPath: JsonPath.optional(),
+    /** Added in 0.4.0. Read one record (`/v1/people/{id}`); needed when their webhook sends only ids. */
+    get: RecordCall.optional(),
+    /** Added in 0.4.0. Create a record Loops made (all mapped fields are filled). Without it, Loops never creates records there. */
+    create: RecordCall.optional(),
+    /** Added in 0.4.0. Update a record: only fields owned by Loops (`owner: ours`) are filled; their fields are left out. */
+    update: RecordCall.optional(),
 });
 export const SyncLink = z.object({
     from: RecordKind,
     to: RecordKind,
+    /** Where the other record's id sits on `from`'s item: a field or a JsonPath; `[*]` for many (`values.associated_people[*].target_record_id`). */
     theirs: z.string().min(1),
+    /** The role on the Loops record link (`recordLinks`), e.g. `decision maker`, `employee`. */
     role: z.string().optional(),
 });
 export const ChangeFeed = z
     .object({
     webhook: z
         .object({
-        signature: z.object({ scheme: z.enum(['hmac-sha256', 'hmac-sha1']), header: z.string().min(1) }),
+        signature: z.object({
+            scheme: z.enum(['hmac-sha256', 'hmac-sha1']),
+            header: z.string().min(1),
+            /** Added in 0.4.0. How the signature is written (default hex). */
+            encoding: z.enum(['hex', 'base64']).optional(),
+            /** Added in 0.4.0. Text before the signature in the header, e.g. `sha256=`. */
+            prefix: z.string().max(40).optional(),
+        }),
+        /** Added in 0.4.0. Where the events sit in one delivery (`events`); the body is one event when left out. */
+        eventsPath: JsonPath.optional(),
+        /** Added in 0.4.0. Where an event says what happened (`event_type`). */
+        typePath: JsonPath.optional(),
+        /** Added in 0.4.0. Where an event names the record (`id.record_id`). */
+        idPath: JsonPath.optional(),
+        /** Added in 0.4.0. Where an event names the object; when it matches no object's `theirs`, the engine asks each object's `get`. */
+        objectPath: JsonPath.optional(),
+        /** Added in 0.4.0. Their event names for each change. A created or updated record is read again with the object's `get`. */
+        types: z
+            .object({
+            created: z.array(z.string().min(1)).default([]),
+            updated: z.array(z.string().min(1)).default([]),
+            deleted: z.array(z.string().min(1)).default([]),
+        })
+            .optional(),
+        /** Added in 0.4.0. Register the webhook through their API at install (`{{hookUrl}}` in the body); the secret is kept in the vault. */
+        register: z
+            .object({
+            call: RecordCall,
+            /** Where the signing secret sits in the answer (`data.secret`). */
+            secretPath: JsonPath,
+            /** Where the webhook's id sits in the answer, to remove it at uninstall. */
+            idPath: JsonPath.optional(),
+            /** Remove it at uninstall; `{id}` is the webhook id. */
+            unregister: RecordCall.optional(),
+        })
+            .optional(),
     })
         .optional(),
-    polling: z.object({ everyMinutes: z.number().int().min(5).max(1440) }).optional(),
+    polling: z.object({
+        everyMinutes: z.number().int().min(5).max(1440),
+        /** Added in 0.4.0. `updatedSince` asks only for changed records (needs list.updatedSinceParam); `full` reads every record and keeps the changed ones. Default: updatedSince when the object has the param, else full. */
+        mode: z.enum(['updatedSince', 'full']).optional(),
+    }).optional(),
 })
     .refine((f) => f.webhook || f.polling, 'Declare a webhook, polling, or both');
 /** What Loops writes back to the CRM timeline (Loops owns these). */
 export const WriteBackKind = z.enum(['call', 'transcript', 'meeting', 'note', 'action', 'campaignReply']);
-export const WriteBack = z.partialRecord(WriteBackKind, z.object({ method: z.enum(['POST', 'PUT', 'PATCH']), path: PathTemplate }));
+export const WriteBack = z.partialRecord(WriteBackKind, z.object({
+    method: z.enum(['POST', 'PUT', 'PATCH']),
+    /** `{id}` = their id of the record the item belongs to, `{object}` = their object name. */
+    path: PathTemplate,
+    /** Added in 0.4.0. Body template; `{{item.*}}` and `{{record.*}}` fill in (sync.ts TEMPLATE_VARIABLES). */
+    body: BodyTemplate.optional(),
+    /** Added in 0.4.0. Where their id of the written item sits in the answer, so Loops can find it again. */
+    idPath: JsonPath.optional(),
+}));
 export const SyncLimits = z.object({
     requestsPerSecond: z.number().positive().max(1000),
     burst: z.number().int().positive().max(10000).optional(),
@@ -92,6 +204,8 @@ export const SyncManifest = z.object({
     changeFeed: ChangeFeed,
     writeBack: WriteBack.default({}),
     limits: SyncLimits,
+    /** Added in 0.4.0. A cheap call that proves the credentials work (`GET /v2/self`). `loops test` and the health check use it. */
+    test: RecordCall.optional(),
 });
 // ── ui: the LoopKit half ────────────────────────────────────────────────────────
 export const SLOTS = [
@@ -176,6 +290,8 @@ export const ManifestV1 = z
     if (new Set(m.scopes).size !== m.scopes.length)
         ctx.addIssue({ code: 'custom', path: ['scopes'], message: 'Scopes are listed twice' });
     m.sync?.objects.forEach((o, i) => need(RECORD_SCOPE[o.ours].write, ['sync', 'objects', i, 'ours'], `Syncing ${o.ours}`));
+    if (m.sync)
+        checkSync(m.sync, ctx);
     if (m.ui) {
         m.ui.uses.forEach((f, i) => need(RECORD_SCOPE[f.split('.')[0]].read, ['ui', 'uses', i], `Reading ${f}`));
         m.ui.does.forEach((d, i) => need(DOES[d], ['ui', 'does', i], `Doing ${d}`));
@@ -206,6 +322,48 @@ export const ManifestV1 = z
         }
     }
 });
+/** Connector checks added in 0.4.0: Loops field names, `{id}` where a record is named, webhook pieces that need each other. */
+function checkSync(sync, ctx) {
+    const issue = (path, message) => ctx.addIssue({ code: 'custom', path: ['sync', ...path], message });
+    const seen = new Set();
+    sync.objects.forEach((o, i) => {
+        if (seen.has(o.theirs))
+            issue(['objects', i, 'theirs'], `${o.theirs} is listed twice`);
+        seen.add(o.theirs);
+        const known = LOOPS_FIELD_NAMES[o.ours];
+        o.fields.forEach((f, j) => {
+            if (!f.ours.startsWith('custom.') && !known.includes(f.ours))
+                issue(['objects', i, 'fields', j, 'ours'], `${f.ours} is not a Loops ${o.ours} field (use one of ${known.join(', ')}, or custom.<key>)`);
+        });
+        o.match.forEach((k, j) => {
+            // A match key names a Loops field (preferred) or, as in 0.3.x manifests, their field; either must be mapped.
+            if (!o.fields.some((f) => f.ours === k || f.theirs === k))
+                issue(['objects', i, 'match', j], `Matching on ${k} needs a field mapped to ${k}`);
+        });
+        for (const call of ['get', 'update']) {
+            if (o[call] && !o[call].path.includes('{id}'))
+                issue(['objects', i, call, 'path'], `The ${call} path needs {id}`);
+        }
+        if (o.list.paging && (o.list.paging.in === 'body') !== (o.list.method === 'POST'))
+            issue(['objects', i, 'list', 'paging', 'in'], 'Paging in the body needs list.method POST, and a POST list pages in the body');
+    });
+    sync.links.forEach((l, i) => {
+        for (const end of ['from', 'to'])
+            if (!sync.objects.some((o) => o.ours === l[end]))
+                issue(['links', i, end], `${l[end]} is linked but no object syncs it`);
+    });
+    const hook = sync.changeFeed.webhook;
+    if (hook?.types && !hook.idPath)
+        issue(['changeFeed', 'webhook', 'idPath'], 'Webhook event types need idPath');
+    if (hook?.types && (hook.types.created.length || hook.types.updated.length))
+        sync.objects.forEach((o, i) => { if (!o.get)
+            issue(['objects', i, 'get'], 'Webhooks that send ids need a get call to read the record'); });
+    if (sync.changeFeed.polling?.mode === 'updatedSince')
+        sync.objects.forEach((o, i) => {
+            if (!o.list.updatedSinceParam)
+                issue(['objects', i, 'list', 'updatedSinceParam'], 'Polling by updatedSince needs list.updatedSinceParam');
+        });
+}
 /** The manifest file name in an app folder. */
 export const MANIFEST_FILE = 'loops.manifest.json';
 /** Parse a manifest; errors come back as plain lines ("ui.uses.0: Reading contact.email needs the contacts:read scope"). */

package/dist/registry.d.ts

@@ -81,6 +81,8 @@ export declare const AppVersionRecord: z.ZodObject<{
                 type: z.ZodLiteral<"apiKey">;
                 header: z.ZodDefault<z.ZodString>;
                 prefix: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                helpUrl: z.ZodOptional<z.ZodURL>;
             }, z.core.$strip>], "type">;
             objects: z.ZodArray<z.ZodObject<{
                 theirs: z.ZodString;
@@ -96,6 +98,39 @@ export declare const AppVersionRecord: z.ZodObject<{
                     cursorParam: z.ZodOptional<z.ZodString>;
                     nextCursorPath: z.ZodOptional<z.ZodString>;
                     updatedSinceParam: z.ZodOptional<z.ZodString>;
+                    method: z.ZodOptional<z.ZodEnum<{
+                        GET: "GET";
+                        POST: "POST";
+                    }>>;
+                    body: z.ZodOptional<z.ZodJSONSchema>;
+                    paging: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        style: z.ZodLiteral<"cursor">;
+                        param: z.ZodString;
+                        nextPath: z.ZodString;
+                        in: z.ZodDefault<z.ZodEnum<{
+                            query: "query";
+                            body: "body";
+                        }>>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        style: z.ZodLiteral<"offset">;
+                        param: z.ZodString;
+                        sizeParam: z.ZodString;
+                        size: z.ZodDefault<z.ZodNumber>;
+                        in: z.ZodDefault<z.ZodEnum<{
+                            query: "query";
+                            body: "body";
+                        }>>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        style: z.ZodLiteral<"page">;
+                        param: z.ZodString;
+                        sizeParam: z.ZodString;
+                        size: z.ZodDefault<z.ZodNumber>;
+                        startAt: z.ZodDefault<z.ZodNumber>;
+                        in: z.ZodDefault<z.ZodEnum<{
+                            query: "query";
+                            body: "body";
+                        }>>;
+                    }, z.core.$strip>], "style">>;
                 }, z.core.$strip>;
                 fields: z.ZodArray<z.ZodObject<{
                     theirs: z.ZodString;
@@ -104,8 +139,60 @@ export declare const AppVersionRecord: z.ZodObject<{
                         theirs: "theirs";
                         ours: "ours";
                     }>;
+                    transform: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                        string: "string";
+                        number: "number";
+                        boolean: "boolean";
+                        trim: "trim";
+                        lower: "lower";
+                        upper: "upper";
+                        isoDate: "isoDate";
+                        first: "first";
+                        domainFromUrl: "domainFromUrl";
+                    }>>>;
                 }, z.core.$strip>>;
                 match: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                idPath: z.ZodOptional<z.ZodString>;
+                updatedAtPath: z.ZodOptional<z.ZodString>;
+                get: z.ZodOptional<z.ZodObject<{
+                    method: z.ZodDefault<z.ZodEnum<{
+                        GET: "GET";
+                        POST: "POST";
+                        PUT: "PUT";
+                        PATCH: "PATCH";
+                        DELETE: "DELETE";
+                    }>>;
+                    path: z.ZodString;
+                    body: z.ZodOptional<z.ZodJSONSchema>;
+                    itemPath: z.ZodOptional<z.ZodString>;
+                    idPath: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                create: z.ZodOptional<z.ZodObject<{
+                    method: z.ZodDefault<z.ZodEnum<{
+                        GET: "GET";
+                        POST: "POST";
+                        PUT: "PUT";
+                        PATCH: "PATCH";
+                        DELETE: "DELETE";
+                    }>>;
+                    path: z.ZodString;
+                    body: z.ZodOptional<z.ZodJSONSchema>;
+                    itemPath: z.ZodOptional<z.ZodString>;
+                    idPath: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                update: z.ZodOptional<z.ZodObject<{
+                    method: z.ZodDefault<z.ZodEnum<{
+                        GET: "GET";
+                        POST: "POST";
+                        PUT: "PUT";
+                        PATCH: "PATCH";
+                        DELETE: "DELETE";
+                    }>>;
+                    path: z.ZodString;
+                    body: z.ZodOptional<z.ZodJSONSchema>;
+                    itemPath: z.ZodOptional<z.ZodString>;
+                    idPath: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
             }, z.core.$strip>>;
             links: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 from: z.ZodEnum<{
@@ -131,10 +218,58 @@ export declare const AppVersionRecord: z.ZodObject<{
                             "hmac-sha1": "hmac-sha1";
                         }>;
                         header: z.ZodString;
+                        encoding: z.ZodOptional<z.ZodEnum<{
+                            hex: "hex";
+                            base64: "base64";
+                        }>>;
+                        prefix: z.ZodOptional<z.ZodString>;
                     }, z.core.$strip>;
+                    eventsPath: z.ZodOptional<z.ZodString>;
+                    typePath: z.ZodOptional<z.ZodString>;
+                    idPath: z.ZodOptional<z.ZodString>;
+                    objectPath: z.ZodOptional<z.ZodString>;
+                    types: z.ZodOptional<z.ZodObject<{
+                        created: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                        updated: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                        deleted: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    }, z.core.$strip>>;
+                    register: z.ZodOptional<z.ZodObject<{
+                        call: z.ZodObject<{
+                            method: z.ZodDefault<z.ZodEnum<{
+                                GET: "GET";
+                                POST: "POST";
+                                PUT: "PUT";
+                                PATCH: "PATCH";
+                                DELETE: "DELETE";
+                            }>>;
+                            path: z.ZodString;
+                            body: z.ZodOptional<z.ZodJSONSchema>;
+                            itemPath: z.ZodOptional<z.ZodString>;
+                            idPath: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strip>;
+                        secretPath: z.ZodString;
+                        idPath: z.ZodOptional<z.ZodString>;
+                        unregister: z.ZodOptional<z.ZodObject<{
+                            method: z.ZodDefault<z.ZodEnum<{
+                                GET: "GET";
+                                POST: "POST";
+                                PUT: "PUT";
+                                PATCH: "PATCH";
+                                DELETE: "DELETE";
+                            }>>;
+                            path: z.ZodString;
+                            body: z.ZodOptional<z.ZodJSONSchema>;
+                            itemPath: z.ZodOptional<z.ZodString>;
+                            idPath: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strip>>;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>>;
                 polling: z.ZodOptional<z.ZodObject<{
                     everyMinutes: z.ZodNumber;
+                    mode: z.ZodOptional<z.ZodEnum<{
+                        updatedSince: "updatedSince";
+                        full: "full";
+                    }>>;
                 }, z.core.$strip>>;
             }, z.core.$strip>;
             writeBack: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
@@ -151,12 +286,27 @@ export declare const AppVersionRecord: z.ZodObject<{
                     PATCH: "PATCH";
                 }>;
                 path: z.ZodString;
+                body: z.ZodOptional<z.ZodJSONSchema>;
+                idPath: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
             limits: z.ZodObject<{
                 requestsPerSecond: z.ZodNumber;
                 burst: z.ZodOptional<z.ZodNumber>;
                 retryAfterHeader: z.ZodDefault<z.ZodString>;
             }, z.core.$strip>;
+            test: z.ZodOptional<z.ZodObject<{
+                method: z.ZodDefault<z.ZodEnum<{
+                    GET: "GET";
+                    POST: "POST";
+                    PUT: "PUT";
+                    PATCH: "PATCH";
+                    DELETE: "DELETE";
+                }>>;
+                path: z.ZodString;
+                body: z.ZodOptional<z.ZodJSONSchema>;
+                itemPath: z.ZodOptional<z.ZodString>;
+                idPath: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
         ui: z.ZodOptional<z.ZodObject<{
             apiVersion: z.ZodLiteral<1>;
@@ -213,10 +363,10 @@ export declare const AppVersionRecord: z.ZodObject<{
             }, z.core.$strip>], "type">>>;
             endpoints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
                 method: z.ZodEnum<{
+                    GET: "GET";
                     POST: "POST";
                     PUT: "PUT";
                     PATCH: "PATCH";
-                    GET: "GET";
                     DELETE: "DELETE";
                 }>;
                 url: z.ZodURL;