@withloops.ai/contracts 0.0.0-stage → 0.2.0

package/src/manifest.ts

@@ -0,0 +1,250 @@
+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';
+
+/**
+ * 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.
+ * Only ever ADD optional fields to v1; a breaking change is manifest v2 and v1 keeps working.
+ */
+
+// ── Shared ──────────────────────────────────────────────────────────────────────
+
+/** Loops record kinds a connector maps into. */
+export const RecordKind = z.enum(['CONTACT', 'COMPANY', 'LEAD', 'DEAL']);
+export type RecordKind = z.infer<typeof RecordKind>;
+
+const RECORD_SCOPE: Record<string, { read: Scope; write: Scope }> = {
+  CONTACT: { read: 'contacts:read', write: 'contacts:write' },
+  COMPANY: { read: 'companies:read', write: 'companies:write' },
+  LEAD: { read: 'leads:read', write: 'leads:write' },
+  DEAL: { read: 'deals:read', write: 'deals:write' },
+  contact: { read: 'contacts:read', write: 'contacts:write' },
+  company: { read: 'companies:read', write: 'companies:write' },
+  lead: { read: 'leads:read', write: 'leads:write' },
+  deal: { read: 'deals:read', write: 'deals:write' },
+  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');
+
+// ── sync: the connector half ────────────────────────────────────────────────────
+
+export const SyncAuth = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('oauth2'),
+    authorizeUrl: HttpsUrl,
+    tokenUrl: HttpsUrl,
+    scopes: z.array(z.string().min(1)).default([]),
+    refresh: z.boolean().default(true),
+  }),
+  z.object({
+    type: z.literal('apiKey'),
+    header: z.string().min(1).default('Authorization'),
+    prefix: z.string().optional(),
+  }),
+]);
+export type SyncAuth = z.infer<typeof SyncAuth>;
+
+/** 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({
+  theirs: z.string().min(1),
+  ours: z.string().min(1),
+  owner: FieldOwner,
+});
+
+export const SyncObject = z.object({
+  theirs: z.string().min(1),
+  ours: RecordKind,
+  list: z.object({
+    path: PathTemplate,
+    itemsPath: z.string().min(1).default('results'),
+    cursorParam: z.string().optional(),
+    nextCursorPath: z.string().optional(),
+    updatedSinceParam: z.string().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([]),
+});
+
+export const SyncLink = z.object({
+  from: RecordKind,
+  to: RecordKind,
+  theirs: z.string().min(1),
+  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) }),
+      })
+      .optional(),
+    polling: z.object({ everyMinutes: z.number().int().min(5).max(1440) }).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 SyncLimits = z.object({
+  requestsPerSecond: z.number().positive().max(1000),
+  burst: z.number().int().positive().max(10000).optional(),
+  retryAfterHeader: z.string().default('Retry-After'),
+});
+
+export const SyncManifest = z.object({
+  baseUrl: HttpsUrl,
+  auth: SyncAuth,
+  objects: z.array(SyncObject).min(1),
+  links: z.array(SyncLink).default([]),
+  changeFeed: ChangeFeed,
+  writeBack: WriteBack.default({}),
+  limits: SyncLimits,
+});
+export type SyncManifest = z.infer<typeof SyncManifest>;
+
+// ── ui: the LoopKit half ────────────────────────────────────────────────────────
+
+export const SLOTS = [
+  'recordPanel',
+  'recordTab',
+  'recordAction',
+  'bulkAction',
+  'composerButton',
+  'messageAction',
+  'loopCard',
+  'linkCard',
+  'crmPanelItem',
+  'settingsPage',
+  'dashboardTile',
+  'simiTool',
+] as const;
+export const Slot = z.enum(SLOTS);
+export type Slot = z.infer<typeof Slot>;
+
+/** Things an app may do in Loops (`LoopKit.do`), and the scope each needs. */
+export const DOES = { 'record.note': 'notes:write', 'loop.post': 'loops:write', 'action.add': 'actions:write' } as const;
+export const Does = z.enum(Object.keys(DOES) as [keyof typeof DOES, ...(keyof typeof DOES)[]]);
+
+/** A field the app reads: `contact.email`, `deal.value`, `loop.title`. */
+export const FieldPath = z.string().regex(/^(contact|company|lead|deal|loop)\.[a-zA-Z][a-zA-Z0-9_]*$/, 'Like contact.email');
+
+/** Where a sent value comes from: a granted field, the link, or the app's settings. */
+export const ValueSource = z
+  .string()
+  .regex(/^((contact|company|lead|deal|loop)\.[a-zA-Z][a-zA-Z0-9_]*|link\.path\.[a-zA-Z][a-zA-Z0-9_]*|settings\.[a-zA-Z][a-zA-Z0-9_]*)$/);
+
+/** A declared response field type: string, number, boolean, date, or enum:a|b|c. */
+export const ReturnType = z.string().regex(/^(string|number|boolean|date|enum:[A-Za-z0-9_-]+(\|[A-Za-z0-9_-]+)*)$/);
+
+export const Endpoint = z.object({
+  method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
+  url: HttpsUrl,
+  sends: z.record(z.string(), ValueSource).default({}),
+  returns: z.record(z.string(), ReturnType),
+});
+export type Endpoint = z.infer<typeof Endpoint>;
+
+export const Setting = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('secret'), label: z.string().min(1).max(80) }),
+  z.object({ type: z.literal('text'), label: z.string().min(1).max(80) }),
+  z.object({ type: z.literal('choice'), label: z.string().min(1).max(80), options: z.array(z.string().min(1)).min(1) }),
+]);
+
+export const UiManifest = z.object({
+  apiVersion: z.literal(1),
+  slots: z.array(Slot).min(1),
+  uses: z.array(FieldPath).default([]),
+  does: z.array(Does).default([]),
+  hears: z.array(EventTypeSchema).default([]),
+  /** Link patterns the app makes cards for, e.g. *.acme.com/report/* (needs the linkCard slot). */
+  links: z.array(z.string().min(3)).default([]),
+  settings: z.record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/), Setting).default({}),
+  endpoints: z.record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/), Endpoint).default({}),
+  /** Entry file of the LoopKit source, relative to the app folder. */
+  entry: z.string().default('src/app.tsx'),
+});
+export type UiManifest = z.infer<typeof UiManifest>;
+
+// ── The manifest ────────────────────────────────────────────────────────────────
+
+export const Developer = z.object({
+  name: z.string().min(1).max(80),
+  email: z.email(),
+  website: HttpsUrl.optional(),
+});
+
+export const Visibility = z.enum(['private', 'public']);
+export type Visibility = z.infer<typeof Visibility>;
+
+export const ManifestV1 = z
+  .object({
+    manifestVersion: z.literal(1),
+    id: AppId,
+    name: z.string().min(2).max(40),
+    version: SemVer,
+    summary: z.string().min(1).max(140),
+    description: z.string().max(4000).optional(),
+    developer: Developer,
+    visibility: Visibility.default('private'),
+    scopes: z.array(ScopeSchema).default([]),
+    sync: SyncManifest.optional(),
+    ui: UiManifest.optional(),
+  })
+  .superRefine((m, ctx) => {
+    if (!m.sync && !m.ui) ctx.addIssue({ code: 'custom', message: 'An app needs a sync half, a ui half, or both', path: [] });
+    const granted = new Set(expandScopes(m.scopes));
+    const need = (scope: Scope, path: (string | number)[], why: string) => {
+      if (!granted.has(scope)) ctx.addIssue({ code: 'custom', path, message: `${why} needs the ${scope} scope` });
+    };
+    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.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}`));
+      m.ui.hears.forEach((e, i) => {
+        const s = scopeForEvent(e);
+        if (s) need(s, ['ui', 'hears', i], `Hearing ${e}`);
+      });
+      if (m.ui.links.length && !m.ui.slots.includes('linkCard'))
+        ctx.addIssue({ code: 'custom', path: ['ui', 'links'], message: 'Links need the linkCard slot' });
+      const uses = new Set(m.ui.uses);
+      const settings = m.ui.settings;
+      for (const [name, ep] of Object.entries(m.ui.endpoints)) {
+        for (const [arg, src] of Object.entries(ep.sends)) {
+          const path = ['ui', 'endpoints', name, 'sends', arg];
+          if (src.startsWith('settings.')) {
+            if (!settings[src.slice(9)]) ctx.addIssue({ code: 'custom', path, message: `${src} is not a declared setting` });
+          } else if (src.startsWith('link.')) {
+            if (!m.ui.slots.includes('linkCard')) ctx.addIssue({ code: 'custom', path, message: 'link values need the linkCard slot' });
+          } else if (!uses.has(src)) {
+            ctx.addIssue({ code: 'custom', path, message: `${src} is sent but not declared in ui.uses` });
+          }
+        }
+      }
+    }
+  });
+export type ManifestV1 = z.infer<typeof ManifestV1>;
+export type ManifestV1Input = z.input<typeof ManifestV1>;
+
+/** 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"). */
+export function parseManifest(input: unknown): { ok: true; manifest: ManifestV1 } | { ok: false; errors: string[] } {
+  const r = ManifestV1.safeParse(input);
+  if (r.success) return { ok: true, manifest: r.data };
+  return { ok: false, errors: r.error.issues.map((i) => `${i.path.join('.') || '(manifest)'}: ${i.message}`) };
+}

package/src/registry.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import { AppId, InstallId, SemVer, Timestamp, UserId, VersionId, WorkspaceId } from './ids.ts';
+import { ManifestV1, Visibility } from './manifest.ts';
+import { ScopeSchema } from './scopes.ts';
+
+/**
+ * Records the control plane (`backend-apps-registry`, D1) keeps, and the RPC surfaces Workers call each other through
+ * (Workers RPC: `WorkerEntrypoint` + service binding; POC passed 11 Nov 2026). Skill §3, §8a.
+ */
+
+// ── Review states (skill §8a) ───────────────────────────────────────────────────
+
+export const REVIEW_STATES = ['submitted', 'checking', 'ai_review', 'awaiting_human', 'approved', 'rejected'] as const;
+export const ReviewState = z.enum(REVIEW_STATES);
+export type ReviewState = z.infer<typeof ReviewState>;
+
+/** Allowed moves. Anything else is refused by the registry. A failure at any step = rejected, instantly. */
+export const REVIEW_TRANSITIONS: Record<ReviewState, readonly ReviewState[]> = {
+  submitted: ['checking', 'rejected'],
+  checking: ['ai_review', 'rejected'],
+  ai_review: ['awaiting_human', 'rejected'],
+  awaiting_human: ['approved', 'rejected'],
+  approved: [],
+  rejected: [],
+};
+
+export function canMove(from: ReviewState, to: ReviewState): boolean {
+  return REVIEW_TRANSITIONS[from].includes(to);
+}
+
+// ── Records ─────────────────────────────────────────────────────────────────────
+
+export const AppRecord = z.object({
+  id: AppId,
+  name: z.string(),
+  summary: z.string(),
+  /** The workspace that owns the app (the developer's workspace). */
+  ownerWorkspaceId: WorkspaceId,
+  createdBy: UserId,
+  visibility: Visibility,
+  /** Latest approved version, shown in the Marketplace; null until one is approved. */
+  liveVersionId: VersionId.nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+});
+export type AppRecord = z.infer<typeof AppRecord>;
+
+export const AppVersionRecord = z.object({
+  id: VersionId,
+  appId: AppId,
+  version: SemVer,
+  manifest: ManifestV1,
+  state: ReviewState,
+  /** Plain-words reasons for a rejection, one per line item. */
+  reasons: z.array(z.string()).default([]),
+  /** Artifacts repo commit this version was built from (null in L0 until submit pushes source). */
+  sourceCommit: z.string().nullable(),
+  submittedBy: UserId,
+  submittedAt: Timestamp,
+  decidedBy: UserId.nullable(),
+  decidedAt: Timestamp.nullable(),
+});
+export type AppVersionRecord = z.infer<typeof AppVersionRecord>;
+
+export const InstallStatus = z.enum(['active', 'paused', 'uninstalled']);
+export type InstallStatus = z.infer<typeof InstallStatus>;
+
+export const InstallRecord = z.object({
+  id: InstallId,
+  appId: AppId,
+  versionId: VersionId,
+  workspaceId: WorkspaceId,
+  installedBy: UserId,
+  /** Scopes the admin approved on the consent sheet. A new scope in a later version needs approval again. */
+  grantedScopes: z.array(ScopeSchema),
+  status: InstallStatus,
+  /** True for a `loops dev` install: visible only to that developer, never reviewed. */
+  dev: z.boolean().default(false),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+});
+export type InstallRecord = z.infer<typeof InstallRecord>;
+
+/** A Marketplace card: what the window lists. */
+export const Listing = z.object({
+  appId: AppId,
+  name: z.string(),
+  summary: z.string(),
+  developerName: z.string(),
+  version: SemVer,
+  scopes: z.array(ScopeSchema),
+  installed: z.boolean(),
+});
+export type Listing = z.infer<typeof Listing>;
+
+// ── Who is calling (resolved from Better Auth + /api/me at the edge) ────────────
+
+export const Caller = z.object({
+  workspaceId: WorkspaceId,
+  userId: UserId,
+  role: z.enum(['owner', 'admin', 'member']),
+  developer: z.boolean(),
+  /** Recruitly SUPER user; the platform is behind a flag, SUPER only, in L0. */
+  superUser: z.boolean(),
+});
+export type Caller = z.infer<typeof Caller>;
+
+// ── RPC surfaces (typed contracts for service bindings) ─────────────────────────
+
+/** `backend-apps-registry` default WorkerEntrypoint. */
+export interface RegistryRpc {
+  submit(caller: Caller, manifest: unknown): Promise<{ ok: true; version: AppVersionRecord } | { ok: false; errors: string[] }>;
+  listMarketplace(caller: Caller): Promise<Listing[]>;
+  /** Apps owned by the caller's workspace (`GET /v1/developer/apps`). Added in 0.2.0. */
+  listApps(caller: Caller): Promise<AppRecord[]>;
+  getApp(caller: Caller, appId: string): Promise<{ app: AppRecord; versions: AppVersionRecord[] } | null>;
+  install(caller: Caller, appId: string, grantedScopes: string[]): Promise<{ ok: true; install: InstallRecord } | { ok: false; error: string }>;
+  uninstall(caller: Caller, installId: string): Promise<{ ok: boolean }>;
+  listInstalls(caller: Caller): Promise<InstallRecord[]>;
+  /** Human review (System Admin, SUPER only). */
+  decide(caller: Caller, versionId: string, decision: 'approved' | 'rejected', reason?: string): Promise<{ ok: boolean; error?: string }>;
+}
+
+/** `backend-apps-engine` default WorkerEntrypoint. */
+export interface EngineRpc {
+  /** Wake the install's Agent after the registry wrote the install row. */
+  installed(install: InstallRecord): Promise<{ ok: true }>;
+  uninstalled(installId: string): Promise<{ ok: true }>;
+  health(): Promise<{ ok: true; version: string }>;
+}

package/src/scopes.ts

@@ -0,0 +1,44 @@
+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',
+} as const;
+
+export type Scope = keyof typeof SCOPES;
+export const SCOPE_NAMES = Object.keys(SCOPES) as [Scope, ...Scope[]];
+export const ScopeSchema = z.enum(SCOPE_NAMES);
+
+/** The consent line for a scope, e.g. on the install sheet. */
+export function consentLine(scope: Scope): string {
+  return SCOPES[scope];
+}
+
+/** A `write` scope implies its `read` (asking for contacts:write shows both lines). */
+export function expandScopes(scopes: readonly Scope[]): Scope[] {
+  const out = new Set<Scope>(scopes);
+  for (const s of scopes) {
+    const [res, op] = s.split(':');
+    const read = `${res}:read`;
+    if (op === 'write' && read in SCOPES) out.add(read as Scope);
+  }
+  return SCOPE_NAMES.filter((s) => out.has(s));
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.