@withpotter/lib 0.13.0-next.101

package/dist/connect/identity.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What a business is allowed to send under.
+ *
+ * Split from the Connect vocabulary because it is a different question. The
+ * rest of that file is about work Box was asked to do; this is about
+ * whether Box is permitted to speak in this business's name at all, and
+ * nothing in the command lifecycle refers to it.
+ */
+/**
+ * A managed sending identity: a domain, a number, a sender ID, a channel.
+ *
+ * §7.4 of the product guide asks for "visible lifecycle and ownership", and
+ * §3.1 and §4 of the business plan make it a billable unit in its own right —
+ * Box charges to provision, verify and renew these. Nothing modelled one,
+ * in either repository, which meant the thing a merchant is billed for was
+ * also the thing they could not see.
+ *
+ * The lifecycle is the product: an identity is not a setting that is on or
+ * off. It is requested, proven to belong to whoever claims it, and then kept
+ * proven — DNS gets edited, numbers get released, sender IDs get revoked by a
+ * regulator, and each of those silently stops delivery on a screen that still
+ * says the identity exists.
+ */
+export type IdentityKind = 'domain' | 'number' | 'sender_id' | 'channel';
+export declare const IDENTITY_KIND_LABEL: Record<IdentityKind, string>;
+/**
+ * Where an identity is in its life.
+ *
+ * `verifying` and `action_required` are deliberately distinct. Both mean not
+ * yet usable, but the first is Box waiting on a provider and the second is
+ * Box waiting on the merchant, and collapsing them produces the single most
+ * common failure in this category: a domain that has sat unverified for three
+ * weeks because one DNS record was never added and nothing ever said so.
+ *
+ * `expiring` exists because a renewal that fails is indistinguishable from a
+ * working identity right up until the morning delivery stops.
+ */
+export type IdentityStatus = 'requested' | 'verifying' | 'action_required' | 'active' | 'expiring' | 'suspended' | 'released';
+export declare const IDENTITY_STATUS_MEANING: Record<IdentityStatus, string>;
+/** One step a merchant must complete themselves, usually a DNS record. */
+export interface IdentityRequirement {
+    id: string;
+    label: string;
+    /** The literal value to paste. Shown verbatim, never re-cased. */
+    value: string;
+    /** What kind of record, where a provider needs it named. */
+    recordType?: string;
+    done: boolean;
+}
+export interface ManagedIdentity {
+    id: string;
+    kind: IdentityKind;
+    /** The domain, number or sender ID itself, exactly as it sends. */
+    value: string;
+    status: IdentityStatus;
+    /** Which channels this identity may carry. */
+    channels: readonly string[];
+    requestedAt: string;
+    verifiedAt?: string;
+    /** When the next renewal or re-verification falls due. */
+    renewsAt?: string;
+    requirements: readonly IdentityRequirement[];
+    /** Why it is blocked, when it is. Never shown otherwise. */
+    problem?: string;
+}
+/** An identity nobody can send from, whatever its row says. */
+export declare function identityBlocked(identity: ManagedIdentity): boolean;

package/dist/connect/identity.js

@@ -0,0 +1,24 @@
+const IDENTITY_KIND_LABEL = {
+  channel: "Channel identity",
+  domain: "Sending domain",
+  number: "Number",
+  sender_id: "Sender ID"
+};
+const IDENTITY_STATUS_MEANING = {
+  action_required: "Waiting on you. Nothing sends until this is finished.",
+  active: "Verified and sending.",
+  expiring: "Renews soon. Delivery stops if the renewal does not complete.",
+  released: "No longer yours. Kept for the record only.",
+  requested: "Asked for. Not provisioned yet.",
+  suspended: "Blocked by Box or the provider while an issue is resolved.",
+  verifying: "Box is checking. No action needed from you."
+};
+function identityBlocked(identity) {
+  return identity.status !== "active" && identity.status !== "expiring";
+}
+export {
+  IDENTITY_KIND_LABEL,
+  IDENTITY_STATUS_MEANING,
+  identityBlocked
+};
+//# sourceMappingURL=identity.js.map

package/dist/connect/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/connect/identity.ts"],"sourcesContent":["/**\n * What a business is allowed to send under.\n *\n * Split from the Connect vocabulary because it is a different question. The\n * rest of that file is about work Box was asked to do; this is about\n * whether Box is permitted to speak in this business's name at all, and\n * nothing in the command lifecycle refers to it.\n */\n/**\n * A managed sending identity: a domain, a number, a sender ID, a channel.\n *\n * §7.4 of the product guide asks for \"visible lifecycle and ownership\", and\n * §3.1 and §4 of the business plan make it a billable unit in its own right —\n * Box charges to provision, verify and renew these. Nothing modelled one,\n * in either repository, which meant the thing a merchant is billed for was\n * also the thing they could not see.\n *\n * The lifecycle is the product: an identity is not a setting that is on or\n * off. It is requested, proven to belong to whoever claims it, and then kept\n * proven — DNS gets edited, numbers get released, sender IDs get revoked by a\n * regulator, and each of those silently stops delivery on a screen that still\n * says the identity exists.\n */\nexport type IdentityKind = 'domain' | 'number' | 'sender_id' | 'channel';\n\nexport const IDENTITY_KIND_LABEL: Record<IdentityKind, string> = {\n  channel: 'Channel identity',\n  domain: 'Sending domain',\n  number: 'Number',\n  sender_id: 'Sender ID',\n};\n\n/**\n * Where an identity is in its life.\n *\n * `verifying` and `action_required` are deliberately distinct. Both mean not\n * yet usable, but the first is Box waiting on a provider and the second is\n * Box waiting on the merchant, and collapsing them produces the single most\n * common failure in this category: a domain that has sat unverified for three\n * weeks because one DNS record was never added and nothing ever said so.\n *\n * `expiring` exists because a renewal that fails is indistinguishable from a\n * working identity right up until the morning delivery stops.\n */\nexport type IdentityStatus =\n  | 'requested'\n  | 'verifying'\n  | 'action_required'\n  | 'active'\n  | 'expiring'\n  | 'suspended'\n  | 'released';\n\nexport const IDENTITY_STATUS_MEANING: Record<IdentityStatus, string> = {\n  action_required: 'Waiting on you. Nothing sends until this is finished.',\n  active: 'Verified and sending.',\n  expiring: 'Renews soon. Delivery stops if the renewal does not complete.',\n  released: 'No longer yours. Kept for the record only.',\n  requested: 'Asked for. Not provisioned yet.',\n  suspended: 'Blocked by Box or the provider while an issue is resolved.',\n  verifying: 'Box is checking. No action needed from you.',\n};\n\n/** One step a merchant must complete themselves, usually a DNS record. */\nexport interface IdentityRequirement {\n  id: string;\n  label: string;\n  /** The literal value to paste. Shown verbatim, never re-cased. */\n  value: string;\n  /** What kind of record, where a provider needs it named. */\n  recordType?: string;\n  done: boolean;\n}\n\nexport interface ManagedIdentity {\n  id: string;\n  kind: IdentityKind;\n  /** The domain, number or sender ID itself, exactly as it sends. */\n  value: string;\n  status: IdentityStatus;\n  /** Which channels this identity may carry. */\n  channels: readonly string[];\n  requestedAt: string;\n  verifiedAt?: string;\n  /** When the next renewal or re-verification falls due. */\n  renewsAt?: string;\n  requirements: readonly IdentityRequirement[];\n  /** Why it is blocked, when it is. Never shown otherwise. */\n  problem?: string;\n}\n\n/** An identity nobody can send from, whatever its row says. */\nexport function identityBlocked(identity: ManagedIdentity): boolean {\n  return identity.status !== 'active' && identity.status !== 'expiring';\n}\n"],"mappings":"AAyBO,MAAM,sBAAoD;AAAA,EAC/D,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,WAAW;AACb;AAuBO,MAAM,0BAA0D;AAAA,EACrE,iBAAiB;AAAA,EACjB,QAAQ;AAAA,EACR,UAAU;AAAA,EACV,UAAU;AAAA,EACV,WAAW;AAAA,EACX,WAAW;AAAA,EACX,WAAW;AACb;AA+BO,SAAS,gBAAgB,UAAoC;AAClE,SAAO,SAAS,WAAW,YAAY,SAAS,WAAW;AAC7D;","names":[]}

package/dist/connect/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Box Connect, as the dashboard sees it.
+ *
+ * Library rather than a screen's private folder, because Connect is not a
+ * place a merchant goes. It is a service whose effects surface wherever the
+ * work already is: a connection lives in Settings, a decision that cannot be
+ * automated lands on the home board, and usage is a line on the bill. Three
+ * unrelated surfaces read this, so it belongs to none of them.
+ */
+export * from './types';
+export * from './identity';
+export * from './catalog';
+export { useCommands, useConnectConfigured, useConnection, useConnections, useIdentities, useRecordTrace, useUsage, } from './use-connect';

package/dist/connect/index.js

@@ -0,0 +1,22 @@
+export * from "./types";
+export * from "./identity";
+export * from "./catalog";
+import {
+  useCommands,
+  useConnectConfigured,
+  useConnection,
+  useConnections,
+  useIdentities,
+  useRecordTrace,
+  useUsage
+} from "./use-connect";
+export {
+  useCommands,
+  useConnectConfigured,
+  useConnection,
+  useConnections,
+  useIdentities,
+  useRecordTrace,
+  useUsage
+};
+//# sourceMappingURL=index.js.map

package/dist/connect/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/connect/index.ts"],"sourcesContent":["/**\n * Box Connect, as the dashboard sees it.\n *\n * Library rather than a screen's private folder, because Connect is not a\n * place a merchant goes. It is a service whose effects surface wherever the\n * work already is: a connection lives in Settings, a decision that cannot be\n * automated lands on the home board, and usage is a line on the bill. Three\n * unrelated surfaces read this, so it belongs to none of them.\n */\nexport * from './types';\nexport * from './identity';\nexport * from './catalog';\nexport {\n  useCommands,\n  useConnectConfigured,\n  useConnection,\n  useConnections,\n  useIdentities,\n  useRecordTrace,\n  useUsage,\n} from './use-connect';\n"],"mappings":"AASA,cAAc;AACd,cAAc;AACd,cAAc;AACd;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}

package/dist/connect/next-up.d.ts

@@ -0,0 +1,18 @@
+import type { NextUpItem } from '@withpotter/components/dashboard/home/next-up-sources';
+import type { CommandRecord, Connection } from './types';
+/**
+ * What Connect owes the merchant, as work on the home board.
+ *
+ * A merchant does not open a log to find out that an invoice never reached
+ * their books, and they should not have to: the failure is silent by nature,
+ * which is exactly why it has to come and find them. So Connect contributes to
+ * the one worklist the business already reads every morning rather than
+ * getting a screen nobody has a reason to visit.
+ *
+ * Both kinds are `blocking`. Neither has a clock, and both stop work that the
+ * merchant believes is happening — a booking that is not reaching the diary,
+ * an invoice Box has stopped re-sending on purpose.
+ */
+export declare function connectNextUp(connections: readonly Connection[], commands: readonly CommandRecord[]): NextUpItem[];
+/** The home board's one line: what Connect owes, ready to sort. */
+export declare function useConnectWork(): NextUpItem[];

package/dist/connect/next-up.js

@@ -0,0 +1,45 @@
+"use client";
+import { productById } from "./catalog";
+import { useCommands, useConnections } from "./use-connect";
+function connectNextUp(connections, commands) {
+  const items = [];
+  for (const connection of connections) {
+    if (connection.health !== "attention_required") continue;
+    const name = productById(connection.productId)?.name ?? "A connection";
+    items.push({
+      id: `connect-broken-${connection.id}`,
+      at: "",
+      title: `${name} has stopped working`,
+      // Name the consequence, not the state. "Connection error" tells a
+      // merchant nothing about what they are losing while it stays broken.
+      meta: "Work is not reaching it while this is unresolved",
+      href: `/dashboard/toolkit/connections/${connection.id}`,
+      stream: "Connections",
+      blocking: true,
+      action: "Reconnect"
+    });
+  }
+  const undecided = commands.filter((c) => c.status === "reconciling");
+  if (undecided.length > 0) {
+    const first = undecided[0];
+    items.push({
+      id: "connect-reconciling",
+      at: "",
+      title: undecided.length === 1 ? "One action is waiting on your answer" : `${undecided.length} actions are waiting on your answer`,
+      meta: "A provider took the work and never confirmed it",
+      href: `/dashboard/toolkit/connections/${first.connectionId}`,
+      stream: "Connections",
+      blocking: true,
+      action: "Decide"
+    });
+  }
+  return items;
+}
+function useConnectWork() {
+  return connectNextUp(useConnections(), useCommands());
+}
+export {
+  connectNextUp,
+  useConnectWork
+};
+//# sourceMappingURL=next-up.js.map

package/dist/connect/next-up.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/connect/next-up.ts"],"sourcesContent":["'use client';\n\nimport type { NextUpItem } from '@withpotter/components/dashboard/home/next-up-sources';\nimport { productById } from './catalog';\nimport type { CommandRecord, Connection } from './types';\nimport { useCommands, useConnections } from './use-connect';\n\n/**\n * What Connect owes the merchant, as work on the home board.\n *\n * A merchant does not open a log to find out that an invoice never reached\n * their books, and they should not have to: the failure is silent by nature,\n * which is exactly why it has to come and find them. So Connect contributes to\n * the one worklist the business already reads every morning rather than\n * getting a screen nobody has a reason to visit.\n *\n * Both kinds are `blocking`. Neither has a clock, and both stop work that the\n * merchant believes is happening — a booking that is not reaching the diary,\n * an invoice Box has stopped re-sending on purpose.\n */\nexport function connectNextUp(\n  connections: readonly Connection[],\n  commands: readonly CommandRecord[],\n): NextUpItem[] {\n  const items: NextUpItem[] = [];\n\n  for (const connection of connections) {\n    if (connection.health !== 'attention_required') continue;\n\n    const name = productById(connection.productId)?.name ?? 'A connection';\n\n    items.push({\n      id: `connect-broken-${connection.id}`,\n      at: '',\n      title: `${name} has stopped working`,\n      // Name the consequence, not the state. \"Connection error\" tells a\n      // merchant nothing about what they are losing while it stays broken.\n      meta: 'Work is not reaching it while this is unresolved',\n      href: `/dashboard/toolkit/connections/${connection.id}`,\n      stream: 'Connections',\n      blocking: true,\n      action: 'Reconnect',\n    });\n  }\n\n  const undecided = commands.filter((c) => c.status === 'reconciling');\n\n  if (undecided.length > 0) {\n    const first = undecided[0];\n\n    items.push({\n      id: 'connect-reconciling',\n      at: '',\n      title:\n        undecided.length === 1\n          ? 'One action is waiting on your answer'\n          : `${undecided.length} actions are waiting on your answer`,\n      meta: 'A provider took the work and never confirmed it',\n      href: `/dashboard/toolkit/connections/${first.connectionId}`,\n      stream: 'Connections',\n      blocking: true,\n      action: 'Decide',\n    });\n  }\n\n  return items;\n}\n\n/** The home board's one line: what Connect owes, ready to sort. */\nexport function useConnectWork(): NextUpItem[] {\n  return connectNextUp(useConnections(), useCommands());\n}\n"],"mappings":";AAGA,SAAS,mBAAmB;AAE5B,SAAS,aAAa,sBAAsB;AAerC,SAAS,cACd,aACA,UACc;AACd,QAAM,QAAsB,CAAC;AAE7B,aAAW,cAAc,aAAa;AACpC,QAAI,WAAW,WAAW,qBAAsB;AAEhD,UAAM,OAAO,YAAY,WAAW,SAAS,GAAG,QAAQ;AAExD,UAAM,KAAK;AAAA,MACT,IAAI,kBAAkB,WAAW,EAAE;AAAA,MACnC,IAAI;AAAA,MACJ,OAAO,GAAG,IAAI;AAAA;AAAA;AAAA,MAGd,MAAM;AAAA,MACN,MAAM,kCAAkC,WAAW,EAAE;AAAA,MACrD,QAAQ;AAAA,MACR,UAAU;AAAA,MACV,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AAEA,QAAM,YAAY,SAAS,OAAO,CAAC,MAAM,EAAE,WAAW,aAAa;AAEnE,MAAI,UAAU,SAAS,GAAG;AACxB,UAAM,QAAQ,UAAU,CAAC;AAEzB,UAAM,KAAK;AAAA,MACT,IAAI;AAAA,MACJ,IAAI;AAAA,MACJ,OACE,UAAU,WAAW,IACjB,yCACA,GAAG,UAAU,MAAM;AAAA,MACzB,MAAM;AAAA,MACN,MAAM,kCAAkC,MAAM,YAAY;AAAA,MAC1D,QAAQ;AAAA,MACR,UAAU;AAAA,MACV,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAGO,SAAS,iBAA+B;AAC7C,SAAO,cAAc,eAAe,GAAG,YAAY,CAAC;AACtD;","names":[]}

package/dist/connect/types.d.ts

@@ -0,0 +1,354 @@
+/**
+ * The words Box Connect uses, kept exactly as the product defines them.
+ *
+ * These are not UI states invented for a screen. Every one of them is a
+ * contract in `withpotter/connect` — the command lifecycle is persisted as
+ * `capability_commands.status`, the availability ladder is what a connector
+ * must climb before it may carry live traffic — and a dashboard that renamed
+ * them would be describing a different product to the merchant than the one
+ * the service is operating.
+ */
+/** The two planes. They share tenancy, policy and metering, nothing else. */
+export type ConnectPlane = 'messaging' | 'integrations';
+/**
+ * How far a product has actually got, in order.
+ *
+ * The ladder is the whole point of this surface. Code, a green build and a
+ * provider's logo in a catalogue are each compatible with a connector that has
+ * never carried a single real message, and every integrations page in the
+ * category shows all three as though they meant "ready". Only
+ * `generally_available` means a merchant can rely on it.
+ */
+export type Availability = 'defined' | 'implemented' | 'fixture_certified' | 'sandbox_certified' | 'pilot' | 'generally_available' | 'suspended' | 'retired';
+/** Whether a merchant can act on this today, and what to offer if not. */
+export declare const CONNECTABLE: readonly Availability[];
+/** What each rung means to the person reading it, in their language. */
+export declare const AVAILABILITY_MEANING: Record<Availability, string>;
+/** A connection's operating state, as the merchant experiences it. */
+export type ConnectionHealth = 'active' | 'attention_required' | 'disconnected' | 'unavailable';
+/**
+ * One command's life, from `CONNECT.md` §8.4.
+ *
+ * `reconciling` is the state that makes this product hard and is the reason
+ * the log is worth reading: the provider may have acted without saying so, and
+ * something has to decide whether the invoice exists before anyone retries.
+ */
+export type CommandStatus = 'accepted' | 'published' | 'processing' | 'retry_scheduled' | 'reconciling' | 'succeeded' | 'failed' | 'expired';
+/** Terminal states. A command here will not move again on its own. */
+export declare const SETTLED: readonly CommandStatus[];
+/** What a workflow does once it is running, in the merchant's words. */
+export type OutcomeShape = 'action' | 'sync' | 'delivery' | 'alert';
+export interface ConnectProduct {
+    id: string;
+    /** Named for the outcome, never for the API. */
+    name: string;
+    /** The provider whose mark this wears, when there is one. */
+    brand?: string;
+    plane: ConnectPlane;
+    shape: OutcomeShape;
+    availability: Availability;
+    /** The sentence a merchant reads to decide. One outcome, no hedging. */
+    outcome: string;
+    /** What they must already have for this to mean anything. */
+    requires: string;
+    /** Exactly what Box would be able to do. Least privilege, stated. */
+    permissions: readonly string[];
+    /** What Box will never do with this grant, where it is worth saying. */
+    limits?: readonly string[];
+}
+export interface CapabilityGrant {
+    id: string;
+    label: string;
+    kind: 'action' | 'sync';
+    /** The manifest version this connection was granted. */
+    version: number;
+    enabled: boolean;
+}
+/** Which way records travel. Said in words on screen, never as an arrow. */
+export type SyncDirection = 'in' | 'out' | 'both';
+/**
+ * A running synchronisation's state.
+ *
+ * `needs_repair` is the one that earns a person's attention: a cursor was
+ * invalidated or a webhook subscription lapsed, so the sync is not merely
+ * behind, it has lost its place and cannot catch up on its own.
+ */
+export type SyncHealth = 'running' | 'paused' | 'needs_repair' | 'rate_limited' | 'completed';
+/**
+ * One thing that crosses the boundary, and whether it does.
+ *
+ * Merge and Nango both give a developer a field map. A merchant is not asking
+ * a mapping question — they are asking what leaves their business, so that is
+ * how it reads here: `leaves` marks the fields that go out to somebody else's
+ * system, and those are the ones a privacy review is about.
+ *
+ * `required` is not a lock for its own sake. An invoice without a total is not
+ * an invoice, and offering to remove it would be offering to break the sync.
+ */
+export interface SyncField {
+    id: string;
+    label: string;
+    included: boolean;
+    required?: boolean;
+    leaves?: boolean;
+}
+export interface SyncState {
+    id: string;
+    /** The thing being kept in step, named as the merchant named it. */
+    label: string;
+    direction: SyncDirection;
+    status: SyncHealth;
+    lastRunAt?: string;
+    /**
+     * How this connector settles a record that changed on both sides.
+     *
+     * The guide requires the policy to be visible rather than implied. A
+     * merchant who does not know which side wins cannot tell a bug from a rule,
+     * and will assume the worst the first time an edit disappears.
+     */
+    conflictPolicy: string;
+    /** Records the policy could not settle on its own. */
+    conflicts: number;
+    fields: readonly SyncField[];
+    /** Why it cannot continue, when it cannot. */
+    problem?: string;
+}
+/**
+ * Who is allowed to use a connection, and for what.
+ *
+ * A connection is granted to the business, but the business is not the only
+ * thing that acts: an automation fires at three in the morning, and an agent
+ * acts on an instruction nobody watched it receive. Least privilege is only
+ * half a promise if a merchant cannot see which of them may do what, so this
+ * is the visible half of a limit the service already enforces.
+ */
+export type UserKind = 'potter' | 'automation' | 'agent' | 'developer';
+export declare const USER_KIND_LABEL: Record<UserKind, string>;
+export interface ConnectionUser {
+    id: string;
+    /** Named as the merchant named it, not as the platform records it. */
+    name: string;
+    kind: UserKind;
+    /**
+     * What this one may do, by grant id.
+     *
+     * Empty means it may use the connection for nothing, which is a real state
+     * and not the same as unrestricted. `null` is the unrestricted case, and
+     * only Box itself is ever that.
+     */
+    allowed: readonly string[] | null;
+    lastUsedAt?: string;
+}
+/**
+ * A thing inside the account that Box may or may not touch.
+ *
+ * One QuickBooks company, one Google calendar, one Slack channel. Authorising
+ * an account is not the same as choosing what inside it is in scope, and every
+ * platform that does this well keeps them separate: GitHub asks for all
+ * repositories or only selected ones, Slack makes you pick the channel, Plaid
+ * makes you pick the accounts. Box asked for neither, so a merchant granted
+ * access to everything and was never told.
+ */
+export interface ConnectionResource {
+    id: string;
+    name: string;
+    /** What it is, in the provider's own words. "Shared calendar", "Private". */
+    detail?: string;
+    selected: boolean;
+}
+/**
+ * Everything in the account, or only what was chosen.
+ *
+ * Kept explicit rather than inferred from an empty selection, because
+ * "everything" and "nothing yet" look identical in a list of unticked boxes
+ * and mean opposite things.
+ */
+export type ResourceScope = 'all' | 'selected';
+export interface Connection {
+    id: string;
+    productId: string;
+    /** The account at the other end, named as the merchant would recognise it. */
+    account: string;
+    health: ConnectionHealth;
+    /** Why it needs attention, when it does. Never shown otherwise. */
+    attention?: string;
+    connectedAt: string;
+    lastActivityAt?: string;
+    grants: readonly CapabilityGrant[];
+    /** What these resources are called here: calendars, channels, companies. */
+    resourceNoun: string;
+    resourceScope: ResourceScope;
+    resources: readonly ConnectionResource[];
+    syncs: readonly SyncState[];
+    users: readonly ConnectionUser[];
+    /**
+     * Who did what to this connection, and when.
+     *
+     * §6.5 asks for "audit history and safe support references" and this is the
+     * half a merchant actually needs: not what the connection DID — the command
+     * log answers that — but what was done TO it. Somebody granted this access,
+     * somebody narrowed it, somebody reconnected it at two in the morning, and
+     * on a shared workspace none of those people is necessarily the person
+     * looking at the screen.
+     */
+    events: readonly ConnectionEvent[];
+    /** Which approved path carries this connection's work. */
+    route?: ConnectionRoute;
+}
+/**
+ * The path from a capability to a provider, as a merchant may see it.
+ *
+ * §7.2 promises "provider health and portability" and §7.1 promises route
+ * pinning. Both were enforced and neither was visible, so a merchant whose
+ * messages had slowed had no way to learn that the route carrying them was
+ * degraded — they only saw their own work failing.
+ *
+ * `version` is shown because pinning is the whole reason a retry is safe: work
+ * already accepted stays on the adapter version responsible for its external
+ * effect, so a provider upgrade cannot change what a half-finished command
+ * does. A merchant does not need to understand that; support does.
+ */
+export type RouteHealth = 'healthy' | 'degraded' | 'unavailable';
+export declare const ROUTE_HEALTH_MEANING: Record<RouteHealth, string>;
+export interface ConnectionRoute {
+    /** The company actually carrying it. Named, because portability is a promise. */
+    provider: string;
+    region: string;
+    health: RouteHealth;
+    /** The pinned adapter version accepted work stays on. */
+    version: number;
+}
+/**
+ * One thing a person did to a connection.
+ *
+ * `actor` is deliberately required. An audit entry that cannot say who is not
+ * an audit entry — it is a timestamp — and the whole reason to keep this
+ * separate from the command log is that everything here has a human behind it.
+ */
+export type ConnectionEventKind = 'authorised' | 'reauthorised' | 'scope_changed' | 'grant_changed' | 'paused' | 'resumed' | 'disconnected';
+export declare const CONNECTION_EVENT_VERB: Record<ConnectionEventKind, string>;
+export interface ConnectionEvent {
+    id: string;
+    kind: ConnectionEventKind;
+    /** The person, named as the workspace knows them. Never a principal id. */
+    actor: string;
+    at: string;
+    /** What changed, when saying so helps. Never the payload. */
+    detail?: string;
+}
+/**
+ * A connection that can reach nothing is not working, whatever its credential
+ * says.
+ *
+ * This is the state every integrations UI leaves people in and none of them
+ * mention: authorised, healthy, and pointed at nothing, so nothing moves and
+ * the screen says it is fine.
+ */
+export declare function reachesNothing(connection: Connection): boolean;
+/**
+ * One attempt at doing the thing, and what came back.
+ *
+ * A count is not evidence. "3 attempts" tells a merchant the number of times
+ * Box tried and nothing about why the first two did not work, which is the
+ * only part that helps anybody. Stripe's request log is the reference here:
+ * every attempt, when, and the provider's own answer.
+ */
+export interface CommandAttemptRecord {
+    number: number;
+    at: string;
+    status: CommandStatus;
+    /** The provider's reason, in the provider's words. Never paraphrased. */
+    reason?: string;
+    /** What the provider called it, once there is something to call. */
+    externalRef?: string;
+}
+export interface CommandRecord {
+    id: string;
+    connectionId: string;
+    /** The business outcome, not the capability name. */
+    summary: string;
+    status: CommandStatus;
+    attempts: readonly CommandAttemptRecord[];
+    /** When Box accepted it, which is not when it was first tried. */
+    acceptedAt: string;
+    occurredAt: string;
+    /** The provider's own reference, once there is one to show. */
+    externalRef?: string;
+    /** Present only when a person has to decide something. */
+    question?: string;
+    /**
+     * The Box record this was done for, when it was done for one.
+     *
+     * Optional because not every command has a subject — a nightly sync belongs
+     * to the connection rather than to any one record — and a required field
+     * would have forced those to invent one.
+     */
+    subject?: CommandSubject;
+    /**
+     * Which channel carried it, when the row came from Box's own message log
+     * rather than from a Connect connection.
+     *
+     * A Connect row identifies its provider through the connection it ran on. A
+     * message Box sent itself has no connection — the channel IS the
+     * identity, and without it every such row would draw the same blank mark.
+     */
+    channel?: string;
+}
+export interface UsageMeter {
+    id: string;
+    label: string;
+    used: number;
+    included: number;
+    unit: string;
+}
+/** Said in words, because an arrow does not say which system wins. */
+export declare const DIRECTION_LABEL: Record<SyncDirection, string>;
+/**
+ * The Box record a command was carried out on behalf of.
+ *
+ * This is the field that turns Connect from a place into a property of the
+ * work. A merchant does not go looking for "the command log" — they open the
+ * order they are worried about and want to know whether the confirmation
+ * reached the customer. §4.4 of the product guide draws exactly this line: the
+ * product owns the customer experience and the business record, Connect owns
+ * the boundary, and the only way both are true at once is if the record can
+ * say what happened outside Box on its behalf.
+ *
+ * Without it every external effect is filed under the provider that performed
+ * it, which is the one filing a merchant never thinks in.
+ */
+export type SubjectKind = 'order' | 'booking' | 'invoice' | 'customer' | 'product' | 'payout' | 'campaign';
+/** What each kind is called where the merchant meets it. */
+export declare const SUBJECT_NOUN: Record<SubjectKind, string>;
+/**
+ * `payout` is a post-transaction FACT, never an instruction.
+ *
+ * Product principle 10 and the business plan's risk table both draw this hard:
+ * Connect may carry an approved fact about money that has already moved — so
+ * an accounting connector can record a settled payout in the books — and it
+ * never authorises, captures, refunds, settles or instructs a payment. A trace
+ * on a payout says "this was written down somewhere else", which is the only
+ * thing it is ever allowed to say.
+ */
+export interface CommandSubject {
+    kind: SubjectKind;
+    /** The record's id in the owning Box product, never Connect's. */
+    id: string;
+}
+/**
+ * The commercial ladder from business plan §11 is DELIBERATELY not here.
+ *
+ * I added it on 24 August and connected it to nothing — the exact
+ * declared-but-not-connected bug this repository keeps producing, committed
+ * by the person writing the rule about it.
+ *
+ * Removing it rather than rendering it, because rendering it would have been
+ * the worse fix. §11's states — requested, qualified, approved to build — are
+ * a leadership gate about whether Box will invest, and a merchant reading
+ * "approved to build" beside a product has been shown an internal decision
+ * that tells them nothing about whether they can use it. That question is
+ * already answered, honestly, by the availability ladder above.
+ *
+ * If the commercial state ever needs a home it is an internal record, not a
+ * field on a merchant-facing catalogue entry.
+ */

package/dist/connect/types.js

@@ -0,0 +1,68 @@
+const CONNECTABLE = [
+  "pilot",
+  "generally_available"
+];
+const AVAILABILITY_MEANING = {
+  defined: "Planned and described here. Not built or available to connect yet.",
+  implemented: "Built and tested here. Never run against the provider.",
+  fixture_certified: "Built and tested end to end. Not yet run against the real provider.",
+  sandbox_certified: "Proven against the provider\u2019s own test system. Not live yet.",
+  pilot: "Live for a few businesses, with support and a way back.",
+  generally_available: "Open to you now, with support behind it.",
+  suspended: "Paused while a safety or provider issue is sorted out.",
+  retired: "Withdrawn. Anyone still on it gets a migration plan."
+};
+const SETTLED = [
+  "succeeded",
+  "failed",
+  "expired"
+];
+const USER_KIND_LABEL = {
+  agent: "Agent",
+  automation: "Automation",
+  developer: "App",
+  potter: "Box"
+};
+const ROUTE_HEALTH_MEANING = {
+  degraded: "Slower than usual. Work is still going out and may take longer to confirm.",
+  healthy: "Working normally.",
+  unavailable: "Not accepting work. Anything sent now waits rather than failing."
+};
+const CONNECTION_EVENT_VERB = {
+  authorised: "connected this account",
+  disconnected: "disconnected it",
+  grant_changed: "changed what Box can do",
+  paused: "paused it",
+  reauthorised: "reconnected it",
+  resumed: "resumed it",
+  scope_changed: "changed what Box may touch"
+};
+function reachesNothing(connection) {
+  return connection.resourceScope === "selected" && connection.resources.every((resource) => !resource.selected);
+}
+const DIRECTION_LABEL = {
+  in: "Into Box",
+  out: "Out to the provider",
+  both: "Both ways"
+};
+const SUBJECT_NOUN = {
+  booking: "booking",
+  campaign: "campaign",
+  customer: "customer",
+  invoice: "invoice",
+  order: "order",
+  payout: "payout",
+  product: "product"
+};
+export {
+  AVAILABILITY_MEANING,
+  CONNECTABLE,
+  CONNECTION_EVENT_VERB,
+  DIRECTION_LABEL,
+  ROUTE_HEALTH_MEANING,
+  SETTLED,
+  SUBJECT_NOUN,
+  USER_KIND_LABEL,
+  reachesNothing
+};
+//# sourceMappingURL=types.js.map