@withloops.ai/contracts 0.3.1 → 0.4.0

package/src/api.ts

@@ -84,6 +84,16 @@ export type ListQuery = z.infer<typeof ListQuery>;
 
 // ── Resources (L0: contacts) ────────────────────────────────────────────────────
 
+/** Where the record also lives (`ExternalRef` in sync.ts), shown so a developer can find their own id. Added in 0.4.0. */
+export const RecordRef = z.object({
+  appId: z.string(),
+  object: z.string(),
+  externalId: z.string(),
+  /** Fields that CRM owns on this record; a PATCH to one answers `conflict`. */
+  lockedFields: z.array(z.string()),
+});
+export type RecordRef = z.infer<typeof RecordRef>;
+
 /** A Loops contact as the public API shows it. camelCase, ids as strings, dates ISO. */
 export const Contact = z.object({
   id: z.string(),
@@ -94,6 +104,8 @@ export const Contact = z.object({
   jobTitle: z.string().nullable(),
   companyId: z.string().nullable(),
   ownerId: z.string().nullable(),
+  /** Added in 0.4.0. Where this contact also lives (a connected CRM). */
+  refs: z.array(RecordRef).optional(),
   createdAt: Timestamp,
   updatedAt: Timestamp,
 });
@@ -122,3 +134,101 @@ export const ContactUpdate = z.object({
   ownerId: z.string().nullable().optional(),
 });
 export type ContactUpdate = z.infer<typeof ContactUpdate>;
+
+// ── Resources added in 0.4.0 (L2): companies, deals, record links ───────────────
+
+
+export const Company = z.object({
+  id: z.string(),
+  name: z.string().nullable(),
+  website: z.string().nullable(),
+  domain: z.string().nullable(),
+  phone: z.string().nullable(),
+  industry: z.string().nullable(),
+  ownerId: z.string().nullable(),
+  refs: z.array(RecordRef).optional(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+});
+export type Company = z.infer<typeof Company>;
+
+export const CompanyCreate = z.object({
+  name: z.string().min(1).max(200),
+  website: z.string().max(500).optional(),
+  phone: z.string().max(40).optional(),
+  industry: z.string().max(120).optional(),
+  ownerId: z.string().optional(),
+});
+export type CompanyCreate = z.infer<typeof CompanyCreate>;
+
+export const CompanyUpdate = z.object({
+  name: z.string().min(1).max(200).optional(),
+  website: z.string().max(500).nullable().optional(),
+  phone: z.string().max(40).nullable().optional(),
+  industry: z.string().max(120).nullable().optional(),
+  ownerId: z.string().nullable().optional(),
+});
+export type CompanyUpdate = z.infer<typeof CompanyUpdate>;
+
+export const Deal = z.object({
+  id: z.string(),
+  name: z.string().nullable(),
+  /** Amount in the currency's units (12500.5). */
+  value: z.number().nullable(),
+  currency: z.string().nullable(),
+  stage: z.string().nullable(),
+  closeDate: z.string().nullable(),
+  companyId: z.string().nullable(),
+  ownerId: z.string().nullable(),
+  refs: z.array(RecordRef).optional(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+});
+export type Deal = z.infer<typeof Deal>;
+
+export const DealCreate = z.object({
+  name: z.string().min(1).max(200),
+  value: z.number().min(0).optional(),
+  currency: z.string().length(3).optional(),
+  stage: z.string().max(120).optional(),
+  closeDate: z.string().optional(),
+  companyId: z.string().optional(),
+  ownerId: z.string().optional(),
+});
+export type DealCreate = z.infer<typeof DealCreate>;
+
+export const DealUpdate = z.object({
+  name: z.string().min(1).max(200).optional(),
+  value: z.number().min(0).nullable().optional(),
+  currency: z.string().length(3).nullable().optional(),
+  stage: z.string().max(120).nullable().optional(),
+  closeDate: z.string().nullable().optional(),
+  companyId: z.string().nullable().optional(),
+  ownerId: z.string().nullable().optional(),
+});
+export type DealUpdate = z.infer<typeof DealUpdate>;
+
+/** Loops record kinds as the API names them in links. */
+export const LinkKind = z.enum(['contact', 'company', 'lead', 'deal']);
+export type LinkKind = z.infer<typeof LinkKind>;
+
+/** A link between two records (`recordLinks` in Vista): a deal holds many people, each with a role. */
+export const RecordLink = z.object({
+  id: z.string(),
+  from: z.object({ kind: LinkKind, id: z.string() }),
+  to: z.object({ kind: LinkKind, id: z.string() }),
+  role: z.string().nullable(),
+  createdAt: Timestamp,
+});
+export type RecordLink = z.infer<typeof RecordLink>;
+
+export const RecordLinkCreate = z.object({
+  from: z.object({ kind: LinkKind, id: z.string().min(1) }),
+  to: z.object({ kind: LinkKind, id: z.string().min(1) }),
+  role: z.string().max(80).optional(),
+});
+export type RecordLinkCreate = z.infer<typeof RecordLinkCreate>;
+
+/** `GET /v1/links?kind=deal&id=…`: the links of one record, either end. */
+export const RecordLinkQuery = z.object({ kind: LinkKind, id: z.string().min(1) });
+export type RecordLinkQuery = z.infer<typeof RecordLinkQuery>;

package/src/fields.ts

@@ -0,0 +1,11 @@
+/**
+ * Added in 0.4.0 (L2). The Loops fields a connector maps into, per record kind. `custom.<key>` reaches a custom field.
+ * Link ids (companyId on a contact, people on a deal) are NOT fields: they come from `sync.links` and become `recordLinks`.
+ * Only ever ADD names here.
+ */
+export const LOOPS_FIELD_NAMES: Record<'CONTACT' | 'COMPANY' | 'LEAD' | 'DEAL', readonly string[]> = {
+  CONTACT: ['firstName', 'lastName', 'email', 'phone', 'mobile', 'jobTitle', 'linkedinUrl', 'city', 'country', 'ownerEmail'],
+  COMPANY: ['name', 'website', 'domain', 'phone', 'industry', 'city', 'country', 'linkedinUrl', 'ownerEmail'],
+  LEAD: ['firstName', 'lastName', 'email', 'phone', 'jobTitle', 'companyName', 'website', 'status', 'source', 'ownerEmail'],
+  DEAL: ['name', 'value', 'currency', 'stage', 'closeDate', 'probability', 'ownerEmail'],
+};

package/src/index.ts

@@ -5,3 +5,5 @@ export * from './manifest.ts';
 export * from './api.ts';
 export * from './registry.ts';
 export * from './trust.ts';
+export * from './fields.ts';
+export * from './sync.ts';

package/src/manifest.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { AppId, HttpsUrl, SemVer } from './ids.ts';
 import { EventTypeSchema, scopeForEvent } from './events.ts';
 import { ScopeSchema, expandScopes, type Scope } from './scopes.ts';
+import { LOOPS_FIELD_NAMES } from './fields.ts';
 
 /**
  * App manifest v1 (`loops.manifest.json`). Everything is a Loops App: one manifest, two optional halves —
@@ -29,6 +30,52 @@ const RECORD_SCOPE: Record<string, { read: Scope; write: Scope }> = {
 
 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'),
+  }),
+]);
+export type Paging = z.infer<typeof Paging>;
+
+/** 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(),
+});
+export type RecordCall = z.infer<typeof RecordCall>;
+
 // ── sync: the connector half ────────────────────────────────────────────────────
 
 export const SyncAuth = z.discriminatedUnion('type', [
@@ -45,6 +92,9 @@ 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(),
   }),
 ]);
 export type SyncAuth = z.infer<typeof SyncAuth>;
@@ -53,9 +103,13 @@ export type SyncAuth = z.infer<typeof SyncAuth>;
 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({
@@ -67,16 +121,34 @@ 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(),
 });
 
@@ -84,10 +156,49 @@ 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');
 
@@ -95,7 +206,15 @@ export const ChangeFeed = z
 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 }),
+  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({
@@ -112,6 +231,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(),
 });
 export type SyncManifest = z.infer<typeof SyncManifest>;
 
@@ -212,6 +333,7 @@ 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}`));
@@ -241,6 +363,42 @@ export const ManifestV1 = z
 export type ManifestV1 = z.infer<typeof ManifestV1>;
 export type ManifestV1Input = z.input<typeof ManifestV1>;
 
+/** 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: SyncManifest, ctx: z.RefinementCtx): void {
+  const issue = (path: (string | number)[], message: string) => ctx.addIssue({ code: 'custom', path: ['sync', ...path], message });
+  const seen = new Set<string>();
+  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'] as const) {
+      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'] as const)
+      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';
 

package/src/sync.ts

@@ -0,0 +1,229 @@
+import { z } from 'zod';
+import { AppId, InstallId, Timestamp, UserId, WorkspaceId } from './ids.ts';
+import { RecordKind, WriteBackKind, 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.
+ */
+
+// ── 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']);
+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 const CrmConnector = z.object({
+  appId: AppId,
+  installId: InstallId,
+  kind: ConnectorKind,
+  setBy: UserId,
+  setAt: Timestamp,
+});
+export type CrmConnector = z.infer<typeof CrmConnector>;
+
+/** 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,
+});
+export type ExternalRef = z.infer<typeof ExternalRef>;
+
+// ── 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 type SyncHealth = z.infer<typeof SyncHealth>;
+
+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 type ObjectProgress = z.infer<typeof ObjectProgress>;
+
+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(),
+});
+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 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()) })),
+    }),
+  ),
+});
+export type MappingPreview = z.infer<typeof MappingPreview>;
+
+/** 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),
+});
+export type SyncSettings = z.infer<typeof SyncSettings>;
+
+// ── 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(),
+});
+export type WriteBackItem = z.infer<typeof WriteBackItem>;
+
+// ── 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'],
+} as const;
+
+// ── The connector driver: what BOTH kinds implement for the engine core ─────────
+
+/** 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;
+
+// ── Engine RPC added in L2 ──────────────────────────────────────────────────────
+
+export const SyncCaller = z.object({ workspaceId: WorkspaceId, userId: UserId });
+
+/** `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 }>;
+}