@withloops.ai/contracts 0.1.0 → 0.2.0

package/dist/api.d.ts

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+/**
+ * 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 declare const API_VERSION: "v1";
+/** Every error code the API returns, with its HTTP status. */
+export declare const ERROR_CODES: {
+    readonly bad_request: 400;
+    readonly validation_failed: 422;
+    readonly unauthorized: 401;
+    readonly forbidden: 403;
+    readonly missing_scope: 403;
+    readonly not_found: 404;
+    readonly conflict: 409;
+    readonly rate_limited: 429;
+    readonly internal: 500;
+    readonly upstream_timeout: 504;
+    readonly unavailable: 503;
+};
+export type ErrorCode = keyof typeof ERROR_CODES;
+export declare const ErrorCodeSchema: z.ZodEnum<{
+    bad_request: "bad_request";
+    validation_failed: "validation_failed";
+    unauthorized: "unauthorized";
+    forbidden: "forbidden";
+    missing_scope: "missing_scope";
+    not_found: "not_found";
+    conflict: "conflict";
+    rate_limited: "rate_limited";
+    internal: "internal";
+    upstream_timeout: "upstream_timeout";
+    unavailable: "unavailable";
+}>;
+export declare const ApiError: z.ZodObject<{
+    code: z.ZodEnum<{
+        bad_request: "bad_request";
+        validation_failed: "validation_failed";
+        unauthorized: "unauthorized";
+        forbidden: "forbidden";
+        missing_scope: "missing_scope";
+        not_found: "not_found";
+        conflict: "conflict";
+        rate_limited: "rate_limited";
+        internal: "internal";
+        upstream_timeout: "upstream_timeout";
+        unavailable: "unavailable";
+    }>;
+    message: z.ZodString;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    scope: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodString;
+}, z.core.$strip>;
+export type ApiError = z.infer<typeof ApiError>;
+export declare const ErrorEnvelope: z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodEnum<{
+            bad_request: "bad_request";
+            validation_failed: "validation_failed";
+            unauthorized: "unauthorized";
+            forbidden: "forbidden";
+            missing_scope: "missing_scope";
+            not_found: "not_found";
+            conflict: "conflict";
+            rate_limited: "rate_limited";
+            internal: "internal";
+            upstream_timeout: "upstream_timeout";
+            unavailable: "unavailable";
+        }>;
+        message: z.ZodString;
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        scope: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ErrorEnvelope = z.infer<typeof ErrorEnvelope>;
+export declare function errorStatus(code: ErrorCode): number;
+export declare const Page: z.ZodObject<{
+    nextCursor: z.ZodNullable<z.ZodString>;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+export type Page = z.infer<typeof Page>;
+/** Single object: `{ ok: true, data }`. */
+export declare function dataEnvelope<T extends z.ZodType>(data: T): z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    data: T;
+}, z.core.$strip>;
+/** List: `{ ok: true, data: [...], page: { nextCursor, hasMore } }`. */
+export declare function listEnvelope<T extends z.ZodType>(item: T): z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    data: z.ZodArray<T>;
+    page: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DataEnvelope<T> = {
+    ok: true;
+    data: T;
+};
+export type ListEnvelope<T> = {
+    ok: true;
+    data: T[];
+    page: Page;
+};
+export declare const PAGE_LIMIT_DEFAULT = 25;
+export declare const PAGE_LIMIT_MAX = 100;
+export declare const ListQuery: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    updatedSince: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type ListQuery = z.infer<typeof ListQuery>;
+/** A Loops contact as the public API shows it. camelCase, ids as strings, dates ISO. */
+export declare const Contact: z.ZodObject<{
+    id: z.ZodString;
+    firstName: z.ZodNullable<z.ZodString>;
+    lastName: z.ZodNullable<z.ZodString>;
+    email: z.ZodNullable<z.ZodEmail>;
+    phone: z.ZodNullable<z.ZodString>;
+    jobTitle: z.ZodNullable<z.ZodString>;
+    companyId: z.ZodNullable<z.ZodString>;
+    ownerId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type Contact = z.infer<typeof Contact>;
+export declare const ContactCreate: z.ZodObject<{
+    firstName: z.ZodOptional<z.ZodString>;
+    lastName: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodEmail>;
+    phone: z.ZodOptional<z.ZodString>;
+    jobTitle: z.ZodOptional<z.ZodString>;
+    companyId: z.ZodOptional<z.ZodString>;
+    ownerId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ContactCreate = z.infer<typeof ContactCreate>;
+export declare const ContactUpdate: z.ZodObject<{
+    firstName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lastName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    email: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    jobTitle: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    companyId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ownerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type ContactUpdate = z.infer<typeof ContactUpdate>;

package/dist/api.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { Timestamp } from "./ids.js";
+/**
+ * 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';
+// ── 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,
+};
+export const ErrorCodeSchema = z.enum(Object.keys(ERROR_CODES));
+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 const ErrorEnvelope = z.object({ ok: z.literal(false), error: ApiError });
+export function errorStatus(code) {
+    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(),
+});
+/** Single object: `{ ok: true, data }`. */
+export function dataEnvelope(data) {
+    return z.object({ ok: z.literal(true), data });
+}
+/** List: `{ ok: true, data: [...], page: { nextCursor, hasMore } }`. */
+export function listEnvelope(item) {
+    return z.object({ ok: z.literal(true), data: z.array(item), 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(),
+});
+// ── 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 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 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(),
+});

package/dist/events.d.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+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 declare const EVENTS: {
+    readonly 'contact.created': "contacts:read";
+    readonly 'contact.updated': "contacts:read";
+    readonly 'contact.deleted': "contacts:read";
+    readonly 'company.created': "companies:read";
+    readonly 'company.updated': "companies:read";
+    readonly 'company.deleted': "companies:read";
+    readonly 'lead.created': "leads:read";
+    readonly 'lead.updated': "leads:read";
+    readonly 'lead.deleted': "leads:read";
+    readonly 'deal.created': "deals:read";
+    readonly 'deal.updated': "deals:read";
+    readonly 'deal.deleted': "deals:read";
+    readonly 'loop.message': "loops:read";
+    readonly 'loop.call.ended': "calls:read";
+    readonly 'meeting.ended': "meetings:read";
+    readonly 'app.installed': null;
+    readonly 'app.uninstalled': null;
+};
+export type EventType = keyof typeof EVENTS;
+export declare const EVENT_TYPES: [EventType, ...EventType[]];
+export declare const EventTypeSchema: z.ZodEnum<{
+    "contact.created": "contact.created";
+    "contact.updated": "contact.updated";
+    "contact.deleted": "contact.deleted";
+    "company.created": "company.created";
+    "company.updated": "company.updated";
+    "company.deleted": "company.deleted";
+    "lead.created": "lead.created";
+    "lead.updated": "lead.updated";
+    "lead.deleted": "lead.deleted";
+    "deal.created": "deal.created";
+    "deal.updated": "deal.updated";
+    "deal.deleted": "deal.deleted";
+    "loop.message": "loop.message";
+    "loop.call.ended": "loop.call.ended";
+    "meeting.ended": "meeting.ended";
+    "app.installed": "app.installed";
+    "app.uninstalled": "app.uninstalled";
+}>;
+/** The scope needed to hear an event; null = every installed app hears it (about itself only). */
+export declare function scopeForEvent(type: EventType): Scope | null;
+/** Who caused a change. Apps never hear their own echo (`causedBy.kind === 'app'` and same app id). */
+export declare const CausedBy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"app">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"system">;
+}, z.core.$strip>], "kind">;
+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 declare const EventEnvelope: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        "contact.created": "contact.created";
+        "contact.updated": "contact.updated";
+        "contact.deleted": "contact.deleted";
+        "company.created": "company.created";
+        "company.updated": "company.updated";
+        "company.deleted": "company.deleted";
+        "lead.created": "lead.created";
+        "lead.updated": "lead.updated";
+        "lead.deleted": "lead.deleted";
+        "deal.created": "deal.created";
+        "deal.updated": "deal.updated";
+        "deal.deleted": "deal.deleted";
+        "loop.message": "loop.message";
+        "loop.call.ended": "loop.call.ended";
+        "meeting.ended": "meeting.ended";
+        "app.installed": "app.installed";
+        "app.uninstalled": "app.uninstalled";
+    }>;
+    version: z.ZodLiteral<1>;
+    occurredAt: z.ZodISODateTime;
+    workspaceId: z.ZodString;
+    installId: z.ZodOptional<z.ZodString>;
+    causedBy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"user">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"app">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"system">;
+    }, z.core.$strip>], "kind">;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type EventEnvelope = z.infer<typeof EventEnvelope>;
+/** True when an app should not get this event back (it caused it). */
+export declare function isEcho(event: Pick<EventEnvelope, 'causedBy'>, appId: string): boolean;

package/dist/events.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { AppId, EventId, InstallId, Timestamp, UserId, WorkspaceId } from "./ids.js";
+/**
+ * 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,
+};
+export const EVENT_TYPES = Object.keys(EVENTS);
+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) {
+    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') }),
+]);
+/**
+ * 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()),
+});
+/** True when an app should not get this event back (it caused it). */
+export function isEcho(event, appId) {
+    return event.causedBy.kind === 'app' && event.causedBy.id === appId;
+}

package/dist/ids.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/** An app's id: the slug chosen at `loops create`, unique across Loops, never changes. */
+export declare const AppId: z.ZodString;
+export type AppId = z.infer<typeof AppId>;
+/** Semantic version of one app release (`1.0.0`, `1.2.0-beta.1`). */
+export declare const SemVer: z.ZodString;
+export type SemVer = z.infer<typeof SemVer>;
+/** A Loops workspace (the customer side; Vista tenant id underneath). */
+export declare const WorkspaceId: z.ZodString;
+export type WorkspaceId = z.infer<typeof WorkspaceId>;
+/** A person in a workspace (Vista user id underneath). */
+export declare const UserId: z.ZodString;
+export type UserId = z.infer<typeof UserId>;
+/** Opaque ids minted by the registry. Prefix shows the kind at a glance in logs. */
+export declare const InstallId: z.ZodString;
+export type InstallId = z.infer<typeof InstallId>;
+export declare const VersionId: z.ZodString;
+export type VersionId = z.infer<typeof VersionId>;
+export declare const EventId: z.ZodString;
+export type EventId = z.infer<typeof EventId>;
+/** ISO 8601 timestamp with offset, e.g. 2026-11-11T09:30:00Z. */
+export declare const Timestamp: z.ZodISODateTime;
+export type Timestamp = z.infer<typeof Timestamp>;
+/** Public https URL. http is refused everywhere in the platform. */
+export declare const HttpsUrl: z.ZodURL;
+export type HttpsUrl = z.infer<typeof HttpsUrl>;

package/dist/ids.js

@@ -0,0 +1,21 @@
+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');
+/** 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');
+/** A Loops workspace (the customer side; Vista tenant id underneath). */
+export const WorkspaceId = z.string().min(1).max(64);
+/** A person in a workspace (Vista user id underneath). */
+export const UserId = z.string().min(1).max(64);
+/** 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 const VersionId = z.string().regex(/^ver_[A-Za-z0-9]{8,40}$/);
+export const EventId = z.string().regex(/^evt_[A-Za-z0-9]{8,40}$/);
+/** ISO 8601 timestamp with offset, e.g. 2026-11-11T09:30:00Z. */
+export const Timestamp = z.iso.datetime({ offset: true });
+/** Public https URL. http is refused everywhere in the platform. */
+export const HttpsUrl = z.url({ protocol: /^https$/ });

package/dist/index.d.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';

package/dist/index.js

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