@withloops.ai/contracts 0.0.0-stage → 0.2.0

package/dist/scopes.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+/**
+ * Every permission an app can ask for. One list for REST, MCP, events and LoopKit (skill §8 "one scope list").
+ * Only ever ADD to this list (versioning promise). `consent` is the plain-words line on the install sheet
+ * ("<App> can …"), sentence case.
+ */
+export declare const SCOPES: {
+    readonly 'contacts:read': "See contacts: names, emails, phone numbers and their company";
+    readonly 'contacts:write': "Add and change contacts";
+    readonly 'companies:read': "See companies";
+    readonly 'companies:write': "Add and change companies";
+    readonly 'leads:read': "See leads";
+    readonly 'leads:write': "Add and change leads";
+    readonly 'deals:read': "See deals and the people on them";
+    readonly 'deals:write': "Add and change deals";
+    readonly 'notes:write': "Write notes on records, marked with the app’s name";
+    readonly 'actions:write': "Add Actions for people in your workspace";
+    readonly 'loops:read': "Read messages in loops the app is added to";
+    readonly 'loops:write': "Post in loops the app is added to, marked with the app’s name";
+    readonly 'calls:read': "See calls and their transcripts";
+    readonly 'meetings:read': "See meetings and their notes";
+    readonly 'webhooks:manage': "Send events from your workspace to the app";
+};
+export type Scope = keyof typeof SCOPES;
+export declare const SCOPE_NAMES: [Scope, ...Scope[]];
+export declare const ScopeSchema: z.ZodEnum<{
+    "contacts:read": "contacts:read";
+    "contacts:write": "contacts:write";
+    "companies:read": "companies:read";
+    "companies:write": "companies:write";
+    "leads:read": "leads:read";
+    "leads:write": "leads:write";
+    "deals:read": "deals:read";
+    "deals:write": "deals:write";
+    "notes:write": "notes:write";
+    "actions:write": "actions:write";
+    "loops:read": "loops:read";
+    "loops:write": "loops:write";
+    "calls:read": "calls:read";
+    "meetings:read": "meetings:read";
+    "webhooks:manage": "webhooks:manage";
+}>;
+/** The consent line for a scope, e.g. on the install sheet. */
+export declare function consentLine(scope: Scope): string;
+/** A `write` scope implies its `read` (asking for contacts:write shows both lines). */
+export declare function expandScopes(scopes: readonly Scope[]): Scope[];

package/dist/scopes.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * Every permission an app can ask for. One list for REST, MCP, events and LoopKit (skill §8 "one scope list").
+ * Only ever ADD to this list (versioning promise). `consent` is the plain-words line on the install sheet
+ * ("<App> can …"), sentence case.
+ */
+export const SCOPES = {
+    'contacts:read': 'See contacts: names, emails, phone numbers and their company',
+    'contacts:write': 'Add and change contacts',
+    'companies:read': 'See companies',
+    'companies:write': 'Add and change companies',
+    'leads:read': 'See leads',
+    'leads:write': 'Add and change leads',
+    'deals:read': 'See deals and the people on them',
+    'deals:write': 'Add and change deals',
+    'notes:write': 'Write notes on records, marked with the app’s name',
+    'actions:write': 'Add Actions for people in your workspace',
+    'loops:read': 'Read messages in loops the app is added to',
+    'loops:write': 'Post in loops the app is added to, marked with the app’s name',
+    'calls:read': 'See calls and their transcripts',
+    'meetings:read': 'See meetings and their notes',
+    'webhooks:manage': 'Send events from your workspace to the app',
+};
+export const SCOPE_NAMES = Object.keys(SCOPES);
+export const ScopeSchema = z.enum(SCOPE_NAMES);
+/** The consent line for a scope, e.g. on the install sheet. */
+export function consentLine(scope) {
+    return SCOPES[scope];
+}
+/** A `write` scope implies its `read` (asking for contacts:write shows both lines). */
+export function expandScopes(scopes) {
+    const out = new Set(scopes);
+    for (const s of scopes) {
+        const [res, op] = s.split(':');
+        const read = `${res}:read`;
+        if (op === 'write' && read in SCOPES)
+            out.add(read);
+    }
+    return SCOPE_NAMES.filter((s) => out.has(s));
+}

package/examples/acme-checks.manifest.json

@@ -0,0 +1,24 @@
+{
+  "manifestVersion": 1,
+  "id": "acme-checks",
+  "name": "Acme Checks",
+  "version": "1.0.0",
+  "summary": "Background checks on your contacts, started from the record.",
+  "developer": { "name": "Acme", "email": "dev@acme-checks.com", "website": "https://acme-checks.com" },
+  "visibility": "public",
+  "scopes": ["contacts:read", "notes:write"],
+  "ui": {
+    "apiVersion": 1,
+    "slots": ["recordTab", "linkCard"],
+    "uses": ["contact.firstName", "contact.email"],
+    "does": ["record.note"],
+    "hears": ["contact.updated"],
+    "links": ["*.acme-checks.com/report/*"],
+    "settings": { "apiKey": { "type": "secret", "label": "Your Acme API key" }, "package": { "type": "choice", "label": "Package", "options": ["Basic", "Enhanced"] } },
+    "endpoints": {
+      "checkStatus": { "method": "GET", "url": "https://api.acme-checks.com/v1/checks/{email}", "sends": { "email": "contact.email" }, "returns": { "status": "enum:clear|pending|flagged", "date": "date" } },
+      "startCheck": { "method": "POST", "url": "https://api.acme-checks.com/v1/checks", "sends": { "name": "contact.firstName", "email": "contact.email", "package": "settings.package" }, "returns": { "id": "string", "status": "enum:pending" } },
+      "report": { "method": "GET", "url": "https://api.acme-checks.com/v1/reports/{id}", "sends": { "id": "link.path.id" }, "returns": { "status": "enum:clear|pending|flagged" } }
+    }
+  }
+}

package/examples/acme-crm.manifest.json

@@ -0,0 +1,114 @@
+{
+  "manifestVersion": 1,
+  "id": "acme-crm",
+  "name": "Acme CRM",
+  "version": "0.1.0",
+  "summary": "Use Acme CRM as your CRM of record; Loops writes calls and notes to its timeline.",
+  "developer": {
+    "name": "Acme",
+    "email": "dev@acme-crm.com",
+    "website": "https://acme-crm.com"
+  },
+  "visibility": "public",
+  "scopes": [
+    "contacts:write",
+    "companies:write"
+  ],
+  "sync": {
+    "baseUrl": "https://api.acme-crm.com",
+    "auth": {
+      "type": "oauth2",
+      "authorizeUrl": "https://app.acme-crm.com/oauth/authorize",
+      "tokenUrl": "https://api.acme-crm.com/oauth/token",
+      "scopes": [
+        "contacts",
+        "companies"
+      ]
+    },
+    "objects": [
+      {
+        "theirs": "people",
+        "ours": "CONTACT",
+        "list": {
+          "path": "/v1/people",
+          "itemsPath": "data",
+          "cursorParam": "cursor",
+          "nextCursorPath": "next_cursor",
+          "updatedSinceParam": "updated_since"
+        },
+        "fields": [
+          {
+            "theirs": "first_name",
+            "ours": "firstName",
+            "owner": "theirs"
+          },
+          {
+            "theirs": "email",
+            "ours": "email",
+            "owner": "theirs"
+          }
+        ],
+        "match": [
+          "email"
+        ]
+      },
+      {
+        "theirs": "organizations",
+        "ours": "COMPANY",
+        "list": {
+          "path": "/v1/organizations",
+          "itemsPath": "data",
+          "cursorParam": "cursor",
+          "nextCursorPath": "next_cursor"
+        },
+        "fields": [
+          {
+            "theirs": "name",
+            "ours": "name",
+            "owner": "theirs"
+          },
+          {
+            "theirs": "domain",
+            "ours": "website",
+            "owner": "theirs"
+          }
+        ],
+        "match": [
+          "domain"
+        ]
+      }
+    ],
+    "links": [
+      {
+        "from": "CONTACT",
+        "to": "COMPANY",
+        "theirs": "organization_id"
+      }
+    ],
+    "changeFeed": {
+      "webhook": {
+        "signature": {
+          "scheme": "hmac-sha256",
+          "header": "X-Acme-Signature"
+        }
+      },
+      "polling": {
+        "everyMinutes": 15
+      }
+    },
+    "writeBack": {
+      "call": {
+        "method": "POST",
+        "path": "/v1/activities"
+      },
+      "note": {
+        "method": "POST",
+        "path": "/v1/notes"
+      }
+    },
+    "limits": {
+      "requestsPerSecond": 10,
+      "burst": 100
+    }
+  }
+}

package/examples/hello.manifest.json

@@ -0,0 +1,14 @@
+{
+  "manifestVersion": 1,
+  "id": "hello",
+  "name": "Hello",
+  "version": "0.1.0",
+  "summary": "Says hello on a contact.",
+  "developer": { "name": "Loops", "email": "developers@withloops.ai" },
+  "scopes": ["contacts:read"],
+  "ui": {
+    "apiVersion": 1,
+    "slots": ["recordPanel"],
+    "uses": ["contact.firstName"]
+  }
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@withloops.ai/contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^24.0.0"
+  },
+  "homepage": "https://withloops.ai",
+  "keywords": [
+    "loops",
+    "withloops",
+    "sdk",
+    "contracts"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/api.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { Timestamp } from './ids.ts';
+
+/**
+ * The public REST API envelope: `api.withloops.ai/v1`. One envelope for every resource, cursor paging, one error shape.
+ * Only ever ADD fields (versioning promise). Hono + @hono/zod-openapi build the OpenAPI spec from these schemas.
+ */
+
+export const API_VERSION = 'v1' as const;
+
+// ── Errors ──────────────────────────────────────────────────────────────────────
+
+/** Every error code the API returns, with its HTTP status. */
+export const ERROR_CODES = {
+  bad_request: 400,
+  validation_failed: 422,
+  unauthorized: 401,
+  forbidden: 403,
+  missing_scope: 403,
+  not_found: 404,
+  conflict: 409,
+  rate_limited: 429,
+  internal: 500,
+  upstream_timeout: 504,
+  unavailable: 503,
+} as const;
+export type ErrorCode = keyof typeof ERROR_CODES;
+export const ErrorCodeSchema = z.enum(Object.keys(ERROR_CODES) as [ErrorCode, ...ErrorCode[]]);
+
+export const ApiError = z.object({
+  code: ErrorCodeSchema,
+  /** Plain words a developer can act on. Never a stack trace, never a secret. */
+  message: z.string(),
+  /** Field-level problems for validation_failed: { "email": "Not an email" }. */
+  fields: z.record(z.string(), z.string()).optional(),
+  /** The scope that was missing, for missing_scope. */
+  scope: z.string().optional(),
+  /** Echoed in the `x-request-id` header; quote it to support. */
+  requestId: z.string(),
+});
+export type ApiError = z.infer<typeof ApiError>;
+
+export const ErrorEnvelope = z.object({ ok: z.literal(false), error: ApiError });
+export type ErrorEnvelope = z.infer<typeof ErrorEnvelope>;
+
+export function errorStatus(code: ErrorCode): number {
+  return ERROR_CODES[code];
+}
+
+// ── Success ─────────────────────────────────────────────────────────────────────
+
+export const Page = z.object({
+  /** Pass as `cursor` to get the next page; null on the last page. */
+  nextCursor: z.string().nullable(),
+  hasMore: z.boolean(),
+});
+export type Page = z.infer<typeof Page>;
+
+/** Single object: `{ ok: true, data }`. */
+export function dataEnvelope<T extends z.ZodType>(data: T) {
+  return z.object({ ok: z.literal(true), data });
+}
+
+/** List: `{ ok: true, data: [...], page: { nextCursor, hasMore } }`. */
+export function listEnvelope<T extends z.ZodType>(item: T) {
+  return z.object({ ok: z.literal(true), data: z.array(item), page: Page });
+}
+
+export type DataEnvelope<T> = { ok: true; data: T };
+export type ListEnvelope<T> = { ok: true; data: T[]; page: Page };
+
+// ── Paging query ────────────────────────────────────────────────────────────────
+
+export const PAGE_LIMIT_DEFAULT = 25;
+export const PAGE_LIMIT_MAX = 100;
+
+export const ListQuery = z.object({
+  cursor: z.string().min(1).optional(),
+  limit: z.coerce.number().int().min(1).max(PAGE_LIMIT_MAX).default(PAGE_LIMIT_DEFAULT),
+  /** Only records changed at or after this time (sync and polling). */
+  updatedSince: Timestamp.optional(),
+});
+export type ListQuery = z.infer<typeof ListQuery>;
+
+// ── Resources (L0: contacts) ────────────────────────────────────────────────────
+
+/** A Loops contact as the public API shows it. camelCase, ids as strings, dates ISO. */
+export const Contact = z.object({
+  id: z.string(),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  email: z.email().nullable(),
+  phone: z.string().nullable(),
+  jobTitle: z.string().nullable(),
+  companyId: z.string().nullable(),
+  ownerId: z.string().nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+});
+export type Contact = z.infer<typeof Contact>;
+
+export const ContactCreate = z
+  .object({
+    firstName: z.string().max(120).optional(),
+    lastName: z.string().max(120).optional(),
+    email: z.email().optional(),
+    phone: z.string().max(40).optional(),
+    jobTitle: z.string().max(200).optional(),
+    companyId: z.string().optional(),
+    ownerId: z.string().optional(),
+  })
+  .refine((c) => c.firstName || c.lastName || c.email, 'Give a name or an email');
+export type ContactCreate = z.infer<typeof ContactCreate>;
+
+export const ContactUpdate = z.object({
+  firstName: z.string().max(120).nullable().optional(),
+  lastName: z.string().max(120).nullable().optional(),
+  email: z.email().nullable().optional(),
+  phone: z.string().max(40).nullable().optional(),
+  jobTitle: z.string().max(200).nullable().optional(),
+  companyId: z.string().nullable().optional(),
+  ownerId: z.string().nullable().optional(),
+});
+export type ContactUpdate = z.infer<typeof ContactUpdate>;

package/src/events.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { AppId, EventId, InstallId, Timestamp, UserId, WorkspaceId } from './ids.ts';
+import type { Scope } from './scopes.ts';
+
+/**
+ * Every event an app can hear (LoopKit `hears`, webhooks out, the engine's queues). Each names the scope that lets an app
+ * hear it. Only ever ADD here (versioning promise).
+ */
+export const EVENTS = {
+  'contact.created': 'contacts:read',
+  'contact.updated': 'contacts:read',
+  'contact.deleted': 'contacts:read',
+  'company.created': 'companies:read',
+  'company.updated': 'companies:read',
+  'company.deleted': 'companies:read',
+  'lead.created': 'leads:read',
+  'lead.updated': 'leads:read',
+  'lead.deleted': 'leads:read',
+  'deal.created': 'deals:read',
+  'deal.updated': 'deals:read',
+  'deal.deleted': 'deals:read',
+  'loop.message': 'loops:read',
+  'loop.call.ended': 'calls:read',
+  'meeting.ended': 'meetings:read',
+  'app.installed': null,
+  'app.uninstalled': null,
+} as const satisfies Record<string, Scope | null>;
+
+export type EventType = keyof typeof EVENTS;
+export const EVENT_TYPES = Object.keys(EVENTS) as [EventType, ...EventType[]];
+export const EventTypeSchema = z.enum(EVENT_TYPES);
+
+/** The scope needed to hear an event; null = every installed app hears it (about itself only). */
+export function scopeForEvent(type: EventType): Scope | null {
+  return EVENTS[type];
+}
+
+/** Who caused a change. Apps never hear their own echo (`causedBy.kind === 'app'` and same app id). */
+export const CausedBy = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('user'), id: UserId }),
+  z.object({ kind: z.literal('app'), id: AppId }),
+  z.object({ kind: z.literal('system') }),
+]);
+export type CausedBy = z.infer<typeof CausedBy>;
+
+/**
+ * The one event envelope. `data` carries ids plus only the fields the app was granted; the engine trims it per install,
+ * so `data` is open here and each consumer narrows it.
+ */
+export const EventEnvelope = z.object({
+  id: EventId,
+  type: EventTypeSchema,
+  version: z.literal(1),
+  occurredAt: Timestamp,
+  workspaceId: WorkspaceId,
+  installId: InstallId.optional(),
+  causedBy: CausedBy,
+  data: z.record(z.string(), z.unknown()),
+});
+export type EventEnvelope = z.infer<typeof EventEnvelope>;
+
+/** True when an app should not get this event back (it caused it). */
+export function isEcho(event: Pick<EventEnvelope, 'causedBy'>, appId: string): boolean {
+  return event.causedBy.kind === 'app' && event.causedBy.id === appId;
+}

package/src/ids.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+/** An app's id: the slug chosen at `loops create`, unique across Loops, never changes. */
+export const AppId = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]{1,38}[a-z0-9]$/, 'App id: 3–40 characters, lowercase letters, digits and dashes, starting with a letter');
+export type AppId = z.infer<typeof AppId>;
+
+/** Semantic version of one app release (`1.0.0`, `1.2.0-beta.1`). */
+export const SemVer = z
+  .string()
+  .regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?$/, 'Version must look like 1.0.0');
+export type SemVer = z.infer<typeof SemVer>;
+
+/** A Loops workspace (the customer side; Vista tenant id underneath). */
+export const WorkspaceId = z.string().min(1).max(64);
+export type WorkspaceId = z.infer<typeof WorkspaceId>;
+
+/** A person in a workspace (Vista user id underneath). */
+export const UserId = z.string().min(1).max(64);
+export type UserId = z.infer<typeof UserId>;
+
+/** Opaque ids minted by the registry. Prefix shows the kind at a glance in logs. */
+export const InstallId = z.string().regex(/^ins_[A-Za-z0-9]{8,40}$/);
+export type InstallId = z.infer<typeof InstallId>;
+
+export const VersionId = z.string().regex(/^ver_[A-Za-z0-9]{8,40}$/);
+export type VersionId = z.infer<typeof VersionId>;
+
+export const EventId = z.string().regex(/^evt_[A-Za-z0-9]{8,40}$/);
+export type EventId = z.infer<typeof EventId>;
+
+/** ISO 8601 timestamp with offset, e.g. 2026-11-11T09:30:00Z. */
+export const Timestamp = z.iso.datetime({ offset: true });
+export type Timestamp = z.infer<typeof Timestamp>;
+
+/** Public https URL. http is refused everywhere in the platform. */
+export const HttpsUrl = z.url({ protocol: /^https$/ });
+export type HttpsUrl = z.infer<typeof HttpsUrl>;

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './ids.ts';
+export * from './scopes.ts';
+export * from './events.ts';
+export * from './manifest.ts';
+export * from './api.ts';
+export * from './registry.ts';