@antasphere/chassis-contract 0.0.0-stage → 1.0.0

package/dist/entitlements.js

@@ -0,0 +1,344 @@
+import { z } from 'zod';
+/**
+ * The billing rail's declaration layer (the pay-per-use billing rail spec,
+ * §7 and §8b): a route says ONCE, next to its contract, what it meters, which
+ * limit it checks and which feature it needs. One chassis middleware reads
+ * the declaration and enforces it for every client of `/api/v1` at once (the
+ * dashboard, the CLI and the MCP tools are all HTTP clients of it), and a
+ * handler never checks or emits by hand.
+ *
+ * Client-safe on purpose: no Hono here. A route is referenced by its
+ * `{ method, path }` as the OpenAPI helper spells it (`{id}` params), so the
+ * tool's contract builds the registry from its route objects and the SDK can
+ * read the same declarations without pulling the server.
+ */
+/**
+ * The plan tiers, a CLOSED enum the hub owns and this contract mirrors so a
+ * tool cannot invent one (§8b). `free` is the default with no subscription;
+ * `pro` is the paid plan. "Enterprise" is not a tier but a per-account
+ * override the hub serves.
+ */
+export const ENTITLEMENT_TIERS = ['free', 'pro'];
+export const entitlementTierSchema = z.enum(ENTITLEMENT_TIERS);
+/** The hub's name for the same closed enum (`BILLING_PLANS` in `@antasphere/contract`). */
+export const BILLING_PLANS = ENTITLEMENT_TIERS;
+/**
+ * The one scope of the tool → hub machine channel (§6): a `client_credentials`
+ * token on the registry client, reaching `/usage/*` and nothing else.
+ */
+export const USAGE_WRITE_SCOPE = 'usage:write';
+/**
+ * The error codes the three tool routes of the hub (`POST /usage/events`,
+ * `GET /usage/entitlements`, `POST /usage/check`) answer with, and the status
+ * each rides on: the hub's `USAGE_ROUTE_ERRORS` (PRDCT-2677).
+ * `tool_credential_required`: the caller is not a registry tool's machine
+ * credential. `unknown_account`: no organization holds the `accountRef` (the
+ * check and the entitlements read; the ingest answers it per event instead).
+ * `validation_error`: the body or the query does not parse. The chassis maps
+ * the check's two (`check.ts`): a 404 `unknown_account` and a 400 are the
+ * hub's judgement, allowed and logged, never an outage.
+ */
+export const USAGE_ROUTE_ERRORS = {
+    tool_credential_required: 401,
+    unknown_account: 404,
+    validation_error: 400
+};
+/**
+ * The wire shape of one usage event as the hub ingests it: the hub's
+ * `usageEventSchema` (`packages/contract/src/schemas/billing.ts` of the hub,
+ * PRDCT-2625), copied here and checked against the hub's wire snapshot
+ * (`wire.ts`, `pnpm --filter @antasphere/chassis-contract wire:check`, the
+ * `hub-wire` CI job; PRDCT-2677), so the fake hub of the test kit refuses
+ * exactly what the real hub refuses (PRDCT-2629). `userId` is the HUB user
+ * (the SSO `sub`), never the tool's local id, and null when the actor is a
+ * resource owner the tool could not name; `accountRef` is the hub
+ * organization id (a uuid) the tool carries as its workspace's central
+ * account id. `toolSlug` is accepted by the hub only when it equals the
+ * calling token's registry slug — the chassis NEVER sends it: the token is
+ * the only authority on the tool's name, the body never names the tool
+ * (PRDCT-2629; `UsageEvent` in seams.ts has no such field).
+ */
+export const usageEventSchema = z
+    .object({
+    id: z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/, 'a ULID'),
+    actionKey: z.string().min(1).max(120).optional(),
+    meter: z.string().min(1).max(120).optional(),
+    quantity: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    unit: z.string().min(1).max(40),
+    occurredAt: z.iso.datetime({ offset: true }),
+    workspaceId: z.string().min(1).max(128),
+    accountRef: z.uuid(),
+    userId: z.string().min(1).max(128).nullable().optional(),
+    via: z.enum(['session', 'api_key', 'oauth']),
+    resourceType: z.string().min(1).max(80).nullable().optional(),
+    resourceId: z.string().min(1).max(256).nullable().optional(),
+    toolSlug: z.string().min(1).max(64).optional(),
+    source: z.object({
+        instanceId: z.string().min(1).max(128),
+        edition: z.string().min(1).max(32),
+        version: z.string().min(1).max(64)
+    })
+})
+    .refine((e) => e.actionKey !== undefined || e.meter !== undefined, {
+    message: 'actionKey (or its legacy alias meter) is required',
+    path: ['actionKey']
+});
+/** The batch cap of `POST /usage/events` (the hub's `USAGE_EVENTS_BATCH_MAX`): at most this many events per post. */
+export const USAGE_EVENTS_BATCH_MAX = 500;
+/**
+ * The body of `POST /usage/events` as the hub parses it (its
+ * `usageEventsBatchSchema`): one to `USAGE_EVENTS_BATCH_MAX` elements, each
+ * judged on its own against `usageEventSchema` afterwards.
+ */
+export const usageEventsBatchSchema = z.object({
+    events: z.array(z.unknown()).min(1).max(USAGE_EVENTS_BATCH_MAX)
+});
+/**
+ * Why the hub did not accept an event (its `USAGE_REJECT_REASONS`, a closed
+ * list): `unknown_account`, `unknown_user`, `tool_mismatch`, and
+ * `invalid_event` (the element does not parse, its `occurredAt` falls outside
+ * the window, or its price exceeds `Number.MAX_SAFE_INTEGER`; `details` names
+ * the field).
+ */
+export const USAGE_REJECT_REASONS = [
+    'unknown_account',
+    'unknown_user',
+    'tool_mismatch',
+    'invalid_event'
+];
+export const usageRejectReasonSchema = z.enum(USAGE_REJECT_REASONS);
+/**
+ * One element's answer. Since phase 2 an `accepted` result carries the
+ * `credits` the hub debited for it (0 when the action has no price).
+ */
+export const usageEventResultSchema = z.object({
+    id: z.string().nullable(),
+    status: z.enum(['accepted', 'duplicate', 'rejected']),
+    reason: usageRejectReasonSchema.optional(),
+    details: z.unknown().optional(),
+    credits: z.number().int().optional()
+});
+/**
+ * The hub's answer to `POST /usage/events`: one result per element, in the
+ * batch's order, and the three counts (always sent).
+ */
+export const usageIngestResultSchema = z.object({
+    results: z.array(usageEventResultSchema),
+    accepted: z.number().int(),
+    duplicate: z.number().int(),
+    rejected: z.number().int()
+});
+// ── The hub's window on an event's date (PRDCT-2630 at the hub, PRDCT-2644 here) ──
+/**
+ * The window an event's `occurredAt` must fall in, measured against the
+ * moment the hub receives it: the hub's `USAGE_EVENT_MAX_PAST_MS` and
+ * `USAGE_EVENT_MAX_FUTURE_MS` (`packages/contract/src/schemas/billing.ts`
+ * of the hub), same names and values, checked against the hub's wire
+ * snapshot (`wire.ts`, `wire:check`, the `hub-wire` CI job; PRDCT-2677). Backward, seven days:
+ * the queue's retry budget is about eight and a half hours, so an outage of
+ * a night is covered many times over, and a week also covers an operator
+ * re-driving held jobs by hand. Forward, five minutes: the skew every JWT
+ * verifier already tolerates; anything further is a clock that is wrong.
+ * Outside the window the hub answers `rejected(invalid_event)` naming
+ * `occurredAt` and never clamps, so the poster refuses BEFORE posting: an
+ * event the hub would refuse on its date is held where it was made, never
+ * counted as a rejection at the hub (PRDCT-2644).
+ */
+export const USAGE_EVENT_MAX_PAST_MS = 7 * 24 * 60 * 60 * 1000;
+export const USAGE_EVENT_MAX_FUTURE_MS = 5 * 60 * 1000;
+/**
+ * Why an event's `occurredAt` is refused against the receipt time, or null
+ * when it falls inside the window (both bounds INCLUSIVE). The hub's
+ * `usageEventOccurrenceIssue`, copied (the wire snapshot's occurrence table
+ * checks it on the hub's offsets): the one comparison both
+ * halves run, the hub at ingest against its own clock, the chassis before
+ * posting against its best estimate of the receipt (its own clock), so the
+ * two never disagree on the sign or the edge.
+ */
+export function usageEventOccurrenceIssue(occurredAt, receivedAt) {
+    const delta = occurredAt.getTime() - receivedAt.getTime();
+    if (delta < -USAGE_EVENT_MAX_PAST_MS) {
+        return {
+            path: 'occurredAt',
+            message: `more than ${USAGE_EVENT_MAX_PAST_MS / 86_400_000} days before the hub received the event`
+        };
+    }
+    if (delta > USAGE_EVENT_MAX_FUTURE_MS) {
+        return {
+            path: 'occurredAt',
+            message: `more than ${USAGE_EVENT_MAX_FUTURE_MS / 60_000} minutes after the hub received the event`
+        };
+    }
+    return null;
+}
+// ── POST /usage/check: the price and the balance before an action (§5, §7 step 3) ──
+/**
+ * The request of `POST /usage/check` (the hub's `UsageCheckRequest`,
+ * PRDCT-2663): the paying account, the action key and the quantity of THIS
+ * request. `unit` is accepted and ignored by the hub, which prices by its
+ * own row; it is sent so the answer's unit can be compared and a mismatch
+ * logged.
+ */
+export const usageCheckRequestSchema = z.object({
+    accountRef: z.uuid(),
+    actionKey: z.string().min(1).max(120),
+    quantity: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    unit: z.string().min(1).max(40).optional()
+});
+/**
+ * The three reasons a check refuses (`null` when allowed), the hub's
+ * `USAGE_CHECK_REASONS`: `account_suspended` (checked first, whatever the
+ * price), `unpriceable` (the price of this quantity exceeds
+ * `Number.MAX_SAFE_INTEGER`: the hub clamps `credits` to that bound, and the
+ * ingest would reject the same event on its `quantity`) and
+ * `insufficient_credits` (`balance < credits`). Each is a refusal, never an
+ * outage (PRDCT-2677).
+ */
+export const USAGE_CHECK_REASONS = ['insufficient_credits', 'account_suspended', 'unpriceable'];
+/**
+ * The hub's answer to `POST /usage/check` (its `UsageCheck`, PRDCT-2663),
+ * checked against the hub's wire snapshot (PRDCT-2677): advisory, no side effect. `credits` is the price of
+ * this quantity from the price book row effective now (0 and `priced:
+ * false` when the tool has no row for the action: views are never priced,
+ * an unknown key is not a refusal); `balance` the account's; `allowed` is
+ * `balance >= credits` unless the organization is suspended, which refuses
+ * whatever the price. `topUpUrl` is always present: the hub's billing page
+ * for that organization, what a `402 entitlement_denied` carries straight
+ * off the answer. No lower bound on `quantity` or `credits`, as at the hub: a
+ * copy stricter than the hub reads a valid answer as an outage.
+ */
+export const usageCheckSchema = z.object({
+    accountRef: z.uuid(),
+    actionKey: z.string(),
+    quantity: z.number().int(),
+    allowed: z.boolean(),
+    credits: z.number().int(),
+    balance: z.number().int(),
+    unit: z.string().nullable(),
+    priced: z.boolean(),
+    plan: entitlementTierSchema,
+    reason: z.enum(USAGE_CHECK_REASONS).nullable(),
+    topUpUrl: z.string()
+});
+/** The wire code of a credit refusal (§7 step 4), and its `details`. */
+export const ENTITLEMENT_DENIED = 'entitlement_denied';
+/** The key of a route's feature declaration, whichever shape it uses; null when none. */
+export function featureKeyOf(entry) {
+    if (!entry.feature)
+        return null;
+    return typeof entry.feature === 'string' ? entry.feature : entry.feature.key;
+}
+/** The actor hook of a route, the entry's own or its meter's; null when the principal is the actor. */
+export function actorHookOf(entry) {
+    return entry.actor ?? entry.meter?.actor ?? null;
+}
+/** `METHOD /path` — the registry key of a route. */
+export function routeEntitlementKey(route) {
+    return `${route.method.toUpperCase()} ${route.path}`;
+}
+/**
+ * Build the registry from the tool's route objects. One entry per route: a
+ * second declaration of the same route throws at module load, so a typo or a
+ * copy cannot silently double or replace a price.
+ */
+export function declareRouteEntitlements(entries) {
+    const map = new Map();
+    for (const entry of entries) {
+        const key = routeEntitlementKey(entry.route);
+        if (map.has(key))
+            throw new Error(`route entitlement declared twice: ${key}`);
+        if (!entry.meter && !entry.limit && !entry.feature) {
+            throw new Error(`route entitlement declares nothing: ${key}`);
+        }
+        map.set(key, entry);
+    }
+    return map;
+}
+/** The declared body size of a request (its `Content-Length`), 0 when absent or malformed. */
+export function declaredContentLength(ctx) {
+    const n = Number(ctx.headers.get('content-length') ?? '0');
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+/**
+ * The stored size a handler recorded in its audit metadata (`sizeBytes`),
+ * falling back to the declared body size before the handler ran. The check
+ * sees the declared size, the emit sees the bytes that were actually kept.
+ */
+export function auditedSizeBytes(ctx) {
+    const stored = ctx.audit?.metadata?.sizeBytes;
+    if (typeof stored === 'number' && Number.isFinite(stored) && stored >= 0)
+        return stored;
+    return declaredContentLength(ctx);
+}
+// ── The tool's declared defaults, as `GET /instance` shows them ────────────
+/**
+ * A priced action: the default the hub seeds its price book from (§7); the
+ * hub's rows win afterwards. `creditsPerUnit` credits buy `per` units of
+ * `unit` (`per` defaults to 1): an action metered in bytes and priced per
+ * mebibyte declares `{ creditsPerUnit: 5, unit: 'bytes', per: 1048576 }`,
+ * so the meter stays exact, the price reads as the seed table says it, and
+ * the two agree by construction (PRDCT-2627: the boot refuses a route whose
+ * meter unit differs from its action's). The hub prices an event as
+ * `creditsPerUnit × quantity / per`; rounding a fraction of a credit is the
+ * hub's rule, not the tool's.
+ */
+export const entitlementActionSchema = z.object({
+    key: z.string().min(1),
+    creditsPerUnit: z.number().int().min(0),
+    unit: z.string().min(1),
+    /** How many units one `creditsPerUnit` buys; 1 when absent. */
+    per: z.number().int().min(1).optional(),
+    label: z.string().min(1)
+});
+/**
+ * The credits an action declares for a quantity: `creditsPerUnit × quantity
+ * / per`, exact (a fraction is the hub's to round). A test pins the seed
+ * values with it, so a unit slip (5 per byte where 5 per MB was meant)
+ * fails before the price book is seeded from discovery.
+ */
+export function declaredCredits(action, quantity) {
+    return (action.creditsPerUnit * quantity) / (action.per ?? 1);
+}
+/** A limit's value per tier plus the oss value (the operator's own knob); null = unlimited. */
+export const tierLimitSchema = z.object({
+    oss: z.number().nullable(),
+    free: z.number().nullable(),
+    pro: z.number().nullable()
+});
+/** A feature's switch per tier (oss has every feature: a self-hosted instance knows no plan). */
+export const tierFeatureSchema = z.object({
+    free: z.boolean(),
+    pro: z.boolean()
+});
+export const toolEntitlementsSchema = z.object({
+    actions: z.array(entitlementActionSchema),
+    limits: z.record(z.string(), tierLimitSchema),
+    features: z.record(z.string(), tierFeatureSchema)
+});
+/**
+ * The hub's answer to `GET /usage/entitlements?accountRef=` (§5): the hub's
+ * `usageEntitlementsSchema` (PRDCT-2636), checked against the hub's wire
+ * snapshot (PRDCT-2677). The account's
+ * plan, resolved from the tier's defaults and the account's overrides; in
+ * phase 1 `limits` and `features` are empty and the tool's own declared
+ * values fill the numbers. A limit's value is a number or a boolean: the
+ * hub may switch a numeric limit off or on per account (`true` = unlimited,
+ * `false` = nothing allowed; `profiles.ts` resolves it so). Since phase 2
+ * (PRDCT-2663) the hub serves its real rows — every limit key it holds for
+ * the calling tool and the features on for the account — and `upgradeUrl`,
+ * its upgrade page for the organization carrying `org`, `tool` and `plan`;
+ * the chassis appends `&key=<key>&requiredPlan=<tier>` at refusal time.
+ * Required: every hub since 0.11.0 sends it.
+ */
+export const entitlementProfileSchema = z.object({
+    accountRef: z.uuid(),
+    plan: entitlementTierSchema,
+    /** Until when the plan is paid for (ISO 8601); null on `free` and on a live subscription. */
+    planUntil: z.string().nullable(),
+    limits: z.record(z.string(), z.union([z.number(), z.boolean()])),
+    features: z.array(z.string()),
+    upgradeUrl: z.string()
+});
+/** The wire code of a plan refusal, and its `details` (§7 step 2). */
+export const PLAN_REQUIRED = 'plan_required';
+//# sourceMappingURL=entitlements.js.map

package/dist/entitlements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.js","sourceRoot":"","sources":["../src/entitlements.ts"],"names":[],"mappings":"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"}

package/dist/identity.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A tool's IDENTITY: every value that names the tool where a person, an agent
+ * or an operator can see it. The chassis packages spell none of them; a tool
+ * writes ONE value of this type (in its own contract package, the one package
+ * its server, SDK, CLI and dashboard all depend on) and hands it to the three
+ * chassis entry points: `defineChassisContract` + `defineChassisRoutes` here,
+ * the server's `ToolDefinition.identity`, and the CLI's `defineCli`.
+ *
+ * Pure data, client-safe. The tool's domain WORDING (a refusal that names its
+ * resource) is not identity: it goes to the server's `copy` slot.
+ */
+export interface ToolIdentity<TScope extends string = string> {
+    /** Machine name, lower case (`acme`): the CLI's config namespace and its hub connect name. */
+    slug: string;
+    /** Human name (`Acme`): mails, the no-dashboard page, CLI messages, the name of an instance not set up yet. */
+    displayName: string;
+    /** API key prefix, without the underscore (`acm` mints `acm_<keyId>_<secret>`). Never change it once keys exist. */
+    apiKeyPrefix: string;
+    /** The scope vocabulary, by the part each scope plays. `dataExport` is the opt-in full-workspace export. */
+    scopes: {
+        read: TScope;
+        write: TScope;
+        dataExport: TScope;
+    };
+    /** How the OpenAPI document names the CLI key's grant (`things:read+write`). A literal: a contraction, not a join. */
+    cliKeyScopesLabel: string;
+    /**
+     * The tool's cloud home (PRDCT-2947): the instance Antasphere operates
+     * (`https://acme.antasphere.com`). The CLI resolves its URL there last
+     * (flag → env → profile → this), so `antasphere login` then `acme list`
+     * works on a clean machine; the implicit `cloud` profile lives at it. A
+     * self-hosted instance is named once, as a profile named for its host.
+     */
+    cloud: {
+        url: string;
+    };
+    cli: {
+        /** The binary's name (`acme`). Must equal the `bin` key of the CLI's package.json. */
+        bin: string;
+        /** Prefix of the CLI's environment variables (`ACME` reads `ACME_URL`, `ACME_API_KEY`, `ACME_WORKSPACE`). */
+        envPrefix: string;
+        /** A pre-hub config directory still read once for migration (`~/.config/<dir>/config.json`). */
+        legacyConfigDir: string;
+    };
+    mcp: {
+        /** `serverInfo.name` of the bundled MCP server. */
+        serverName: string;
+        /** Prefix of the tool's MCP tool names, underscore included (`acme_`). The tool registers `<prefix>whoami`. */
+        toolPrefix: string;
+    };
+    /** OpenTelemetry `service.name`. */
+    otelServiceName: string;
+    /** The published container image. Read by nothing at run time: recorded so an instantiate script has one source. */
+    imageName: string;
+}
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IAC1D,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,WAAW,EAAE,MAAM,CAAC;IACpB,oHAAoH;IACpH,YAAY,EAAE,MAAM,CAAC;IACrB,4GAA4G;IAC5G,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,sHAAsH;IACtH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACvB,GAAG,EAAE;QACH,sFAAsF;QACtF,GAAG,EAAE,MAAM,CAAC;QACZ,6GAA6G;QAC7G,SAAS,EAAE,MAAM,CAAC;QAClB,gGAAgG;QAChG,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,GAAG,EAAE;QACH,mDAAmD;QACnD,UAAU,EAAE,MAAM,CAAC;QACnB,+GAA+G;QAC/G,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,oCAAoC;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,oHAAoH;IACpH,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/identity.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export * from './schemas/common.js';
+export * from './schemas/scope.js';
+export * from './schemas/instance.js';
+export * from './schemas/setup.js';
+export { onboardingDismissedSchema, type OnboardingDismissed } from './schemas/me.js';
+export * from './schemas/workspaces.js';
+export * from './schemas/members.js';
+export { cliAuthRequestSchema, cliAuthRequestedSchema, cliAuthCompleteSchema, cliAuthRevokedSchema, type CliAuthRequest, type CliAuthRequested, type CliAuthComplete, type CliAuthRevoked } from './schemas/cli-auth.js';
+export * from './schemas/sso-connect.js';
+export * from './schemas/sso-logout.js';
+export * from './schemas/invitations.js';
+export * from './schemas/audit.js';
+export * from './schemas/break-glass.js';
+export * from './schemas/files.js';
+export * from './schemas/projects.js';
+export * from './schemas/teams.js';
+export * from './schemas/demo-passes.js';
+export * from './seams.js';
+export * from './entitlements.js';
+export * from './wire.js';
+export * from './define.js';
+export type { ToolIdentity } from './identity.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,yBAAyB,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtF,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+// Client-safe entry: pure zod schemas + seam types. No Hono anywhere on this
+// path — the dashboard and SDK import from here and must stay server-free.
+//
+// The generic half of the platform contract. Everything is a static export
+// EXCEPT what carries the tool's scope vocabulary: that comes out of
+// `defineChassisContract({ scopes })`, instantiated once by the tool from its
+// identity (`ToolIdentity`, ./identity.ts: the type only, the value is the tool's).
+export * from './schemas/common.js';
+export * from './schemas/scope.js';
+export * from './schemas/instance.js';
+export * from './schemas/setup.js';
+export { onboardingDismissedSchema } from './schemas/me.js';
+export * from './schemas/workspaces.js';
+export * from './schemas/members.js';
+export { cliAuthRequestSchema, cliAuthRequestedSchema, cliAuthCompleteSchema, cliAuthRevokedSchema } from './schemas/cli-auth.js';
+export * from './schemas/sso-connect.js';
+export * from './schemas/sso-logout.js';
+export * from './schemas/invitations.js';
+export * from './schemas/audit.js';
+export * from './schemas/break-glass.js';
+export * from './schemas/files.js';
+export * from './schemas/projects.js';
+export * from './schemas/teams.js';
+export * from './schemas/demo-passes.js';
+export * from './seams.js';
+export * from './entitlements.js';
+export * from './wire.js';
+export * from './define.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,EAAE;AACF,2EAA2E;AAC3E,qEAAqE;AACrE,8EAA8E;AAC9E,oFAAoF;AACpF,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,yBAAyB,EAA4B,MAAM,iBAAiB,CAAC;AACtF,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EAKrB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}