@withpotter/lib 0.13.0-next.101

package/dist/connect/types.js.map

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

package/dist/connect/use-connect.d.ts

@@ -0,0 +1,51 @@
+import type { CommandRecord, Connection, SubjectKind } from './types';
+import type { ManagedIdentity } from './identity';
+export declare function useConnections(): readonly Connection[];
+export declare function useConnection(id: string): Connection | undefined;
+export declare function useCommands(connectionId?: string): readonly CommandRecord[];
+export declare function useUsage(): readonly import("./types").UsageMeter[];
+/**
+ * Whether this workspace's Box is wired to Connect at all.
+ *
+ * A deployment without it is not broken and has no connections, which is a
+ * different thing from a deployment that has one and cannot reach it. Asking
+ * first is what lets a screen say the true one.
+ *
+ * The read model above is still fixture-backed, because Connect exposes one
+ * connection by id and nothing that lists them, and does not yet model the
+ * resources, users or syncs these screens show. Those endpoints are the
+ * remaining work. The actions are real.
+ */
+export declare function useConnectConfigured(): boolean;
+/**
+ * What Box did outside Box on this record's behalf.
+ *
+ * The hook behind every trace. It is the same log the connection page shows,
+ * asked the question a merchant actually has: not "what has QuickBooks been
+ * doing" but "did anything happen to *this order*". A command with no subject
+ * — a nightly sync, a token refresh — belongs to the connection and is
+ * correctly absent here.
+ *
+ * Newest first, because on a record the question is nearly always about the
+ * most recent thing, which is the opposite of the connection log where the
+ * unresolved item leads.
+ */
+export declare function useRecordTrace(kind: SubjectKind, id?: string, 
+/**
+ * The address to ask about instead of a reference.
+ *
+ * A customer has no reference of their own and should not have one: a
+ * message is about an order or a booking, and the person is who it reached.
+ * So their trace is answered by what was sent TO them, which is a different
+ * question with a different key.
+ */
+recipient?: string): readonly CommandRecord[];
+/**
+ * The identities this workspace sends from.
+ *
+ * Billable in their own right (business plan §3.1, §4), which is the reason
+ * they cannot stay invisible: a merchant charged for a sending domain has to
+ * be able to see the domain, and see that it is the one thing standing between
+ * them and a delivered email.
+ */
+export declare function useIdentities(): readonly ManagedIdentity[];

package/dist/connect/use-connect.js

@@ -0,0 +1,85 @@
+"use client";
+import { useMemo, useSyncExternalStore } from "react";
+import { useApiQuery } from "@withpotter/hooks/use-api-query";
+import { communicationsApi } from "@withpotter/lib/api/communications";
+import { connectApi } from "@withpotter/lib/api/connect";
+import { traceFromNotification } from "./from-notifications";
+import {
+  FIXTURE_COMMANDS,
+  FIXTURE_CONNECTIONS,
+  FIXTURE_IDENTITIES,
+  FIXTURE_USAGE
+} from "./fixtures";
+const subscribeToNothing = () => () => {
+};
+const readPreview = () => new URLSearchParams(window.location.search).get("preview") === "connect";
+const serverPreview = () => false;
+function usePreview() {
+  return useSyncExternalStore(subscribeToNothing, readPreview, serverPreview);
+}
+function useConnections() {
+  const preview = usePreview();
+  return preview ? FIXTURE_CONNECTIONS : EMPTY_CONNECTIONS;
+}
+const EMPTY_CONNECTIONS = [];
+const EMPTY_COMMANDS = [];
+function useConnection(id) {
+  const connections = useConnections();
+  return useMemo(() => connections.find((c) => c.id === id), [connections, id]);
+}
+function useCommands(connectionId) {
+  const preview = usePreview();
+  return useMemo(() => {
+    if (!preview) return EMPTY_COMMANDS;
+    return connectionId ? FIXTURE_COMMANDS.filter((c) => c.connectionId === connectionId) : FIXTURE_COMMANDS;
+  }, [connectionId, preview]);
+}
+function useUsage() {
+  const preview = usePreview();
+  return preview ? FIXTURE_USAGE : [];
+}
+function useConnectConfigured() {
+  const { data } = useApiQuery(
+    ["connect-status"],
+    (slug) => connectApi.status(slug)
+  );
+  return data?.configured ?? false;
+}
+const EMPTY_IDENTITIES = [];
+function useRecordTrace(kind, id, recipient) {
+  const preview = usePreview();
+  const byRecipient = kind === "customer";
+  const key = byRecipient ? recipient : id;
+  const { data } = useApiQuery(
+    ["notification-trace", kind, key ?? ""],
+    (slug) => communicationsApi.listLogs(slug, {
+      limit: 20,
+      ...byRecipient ? { recipient: key } : { reference: key }
+    }),
+    { enabled: !preview && Boolean(key) }
+  );
+  return useMemo(() => {
+    if (preview) {
+      if (!id) return EMPTY_COMMANDS;
+      return FIXTURE_COMMANDS.filter(
+        (command) => command.subject?.kind === kind && command.subject.id === id
+      ).sort((a, b) => b.occurredAt.localeCompare(a.occurredAt));
+    }
+    const items = data?.items ?? [];
+    return items.map(traceFromNotification).sort((a, b) => b.occurredAt.localeCompare(a.occurredAt));
+  }, [data, id, kind, preview]);
+}
+function useIdentities() {
+  const preview = usePreview();
+  return preview ? FIXTURE_IDENTITIES : EMPTY_IDENTITIES;
+}
+export {
+  useCommands,
+  useConnectConfigured,
+  useConnection,
+  useConnections,
+  useIdentities,
+  useRecordTrace,
+  useUsage
+};
+//# sourceMappingURL=use-connect.js.map

package/dist/connect/use-connect.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/connect/use-connect.ts"],"sourcesContent":["'use client';\n\nimport { useMemo, useSyncExternalStore } from 'react';\nimport { useApiQuery } from '@withpotter/hooks/use-api-query';\nimport { communicationsApi } from '@withpotter/lib/api/communications';\nimport { connectApi, type ConnectStatus } from '@withpotter/lib/api/connect';\nimport type { NotificationLogPage } from '@withpotter/lib/api/types/crm';\nimport { traceFromNotification } from './from-notifications';\nimport {\n  FIXTURE_COMMANDS,\n  FIXTURE_CONNECTIONS,\n  FIXTURE_IDENTITIES,\n  FIXTURE_USAGE,\n} from './fixtures';\nimport type { CommandRecord, Connection, SubjectKind } from './types';\nimport type { ManagedIdentity } from './identity';\n\n/**\n * The one seam between these screens and where Connect state comes from.\n *\n * Every surface that shows Connect state reads through this file and nothing\n * else, so wiring the real service is a change here rather than a change\n * everywhere. Until `withpotter/connect` is proxied through potter-api there\n * is nothing to read, and the honest answer is none.\n */\n\n/**\n * Show the sample operating state, on request only.\n *\n * These screens have to be buildable and reviewable before the service they\n * describe is reachable, and the way that usually goes wrong is a fixture that\n * outlives the prototype: a merchant opens Connections and is told they have a\n * QuickBooks company connected. So the sample state is off unless somebody\n * asks for it with `?preview=connect`, and a real workspace can never see it\n * by accident.\n *\n * Read off `window.location` rather than `useSearchParams`, which would force\n * every page that touches Connect into a Suspense boundary for a debugging\n * affordance. Through `useSyncExternalStore` rather than an effect that writes\n * state, so the server and the first client render agree instead of the page\n * painting once and then correcting itself.\n */\nconst subscribeToNothing = () => () => {};\n\nconst readPreview = () =>\n  new URLSearchParams(window.location.search).get('preview') === 'connect';\n\nconst serverPreview = () => false;\n\nfunction usePreview(): boolean {\n  return useSyncExternalStore(subscribeToNothing, readPreview, serverPreview);\n}\n\nexport function useConnections(): readonly Connection[] {\n  const preview = usePreview();\n  return preview ? FIXTURE_CONNECTIONS : EMPTY_CONNECTIONS;\n}\n\nconst EMPTY_CONNECTIONS: readonly Connection[] = [];\nconst EMPTY_COMMANDS: readonly CommandRecord[] = [];\n\nexport function useConnection(id: string): Connection | undefined {\n  const connections = useConnections();\n  return useMemo(() => connections.find((c) => c.id === id), [connections, id]);\n}\n\nexport function useCommands(connectionId?: string): readonly CommandRecord[] {\n  const preview = usePreview();\n\n  return useMemo(() => {\n    if (!preview) return EMPTY_COMMANDS;\n\n    return connectionId\n      ? FIXTURE_COMMANDS.filter((c) => c.connectionId === connectionId)\n      : FIXTURE_COMMANDS;\n  }, [connectionId, preview]);\n}\n\nexport function useUsage() {\n  const preview = usePreview();\n  return preview ? FIXTURE_USAGE : [];\n}\n\n/**\n * Whether this workspace's Box is wired to Connect at all.\n *\n * A deployment without it is not broken and has no connections, which is a\n * different thing from a deployment that has one and cannot reach it. Asking\n * first is what lets a screen say the true one.\n *\n * The read model above is still fixture-backed, because Connect exposes one\n * connection by id and nothing that lists them, and does not yet model the\n * resources, users or syncs these screens show. Those endpoints are the\n * remaining work. The actions are real.\n */\nexport function useConnectConfigured(): boolean {\n  const { data } = useApiQuery<ConnectStatus>(['connect-status'], (slug) =>\n    connectApi.status(slug),\n  );\n\n  return data?.configured ?? false;\n}\n\nconst EMPTY_IDENTITIES: readonly ManagedIdentity[] = [];\n\n/**\n * What Box did outside Box on this record's behalf.\n *\n * The hook behind every trace. It is the same log the connection page shows,\n * asked the question a merchant actually has: not \"what has QuickBooks been\n * doing\" but \"did anything happen to *this order*\". A command with no subject\n * — a nightly sync, a token refresh — belongs to the connection and is\n * correctly absent here.\n *\n * Newest first, because on a record the question is nearly always about the\n * most recent thing, which is the opposite of the connection log where the\n * unresolved item leads.\n */\nexport function useRecordTrace(\n  kind: SubjectKind,\n  id?: string,\n  /**\n   * The address to ask about instead of a reference.\n   *\n   * A customer has no reference of their own and should not have one: a\n   * message is about an order or a booking, and the person is who it reached.\n   * So their trace is answered by what was sent TO them, which is a different\n   * question with a different key.\n   */\n  recipient?: string,\n): readonly CommandRecord[] {\n  const preview = usePreview();\n\n  const byRecipient = kind === 'customer';\n\n  const key = byRecipient ? recipient : id;\n\n  /**\n   * Box's own message log, which has the answer today.\n   *\n   * When Connect becomes reachable it is a second source behind this same\n   * hook, and no screen changes.\n   */\n  const { data } = useApiQuery<NotificationLogPage>(\n    ['notification-trace', kind, key ?? ''],\n    (slug) =>\n      communicationsApi.listLogs(slug, {\n        limit: 20,\n        ...(byRecipient ? { recipient: key } : { reference: key }),\n      }),\n    { enabled: !preview && Boolean(key) },\n  );\n\n  return useMemo(() => {\n    if (preview) {\n      if (!id) return EMPTY_COMMANDS;\n\n      return FIXTURE_COMMANDS.filter(\n        (command) =>\n          command.subject?.kind === kind && command.subject.id === id,\n      ).sort((a, b) => b.occurredAt.localeCompare(a.occurredAt));\n    }\n\n    const items = data?.items ?? [];\n\n    // Newest first. On a record the question is nearly always about the most\n    // recent thing, which is the opposite of the connection log where the\n    // unresolved item leads.\n    return items\n      .map(traceFromNotification)\n      .sort((a, b) => b.occurredAt.localeCompare(a.occurredAt));\n  }, [data, id, kind, preview]);\n}\n\n/**\n * The identities this workspace sends from.\n *\n * Billable in their own right (business plan §3.1, §4), which is the reason\n * they cannot stay invisible: a merchant charged for a sending domain has to\n * be able to see the domain, and see that it is the one thing standing between\n * them and a delivered email.\n */\nexport function useIdentities(): readonly ManagedIdentity[] {\n  const preview = usePreview();\n  return preview ? FIXTURE_IDENTITIES : EMPTY_IDENTITIES;\n}\n"],"mappings":";AAEA,SAAS,SAAS,4BAA4B;AAC9C,SAAS,mBAAmB;AAC5B,SAAS,yBAAyB;AAClC,SAAS,kBAAsC;AAE/C,SAAS,6BAA6B;AACtC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA6BP,MAAM,qBAAqB,MAAM,MAAM;AAAC;AAExC,MAAM,cAAc,MAClB,IAAI,gBAAgB,OAAO,SAAS,MAAM,EAAE,IAAI,SAAS,MAAM;AAEjE,MAAM,gBAAgB,MAAM;AAE5B,SAAS,aAAsB;AAC7B,SAAO,qBAAqB,oBAAoB,aAAa,aAAa;AAC5E;AAEO,SAAS,iBAAwC;AACtD,QAAM,UAAU,WAAW;AAC3B,SAAO,UAAU,sBAAsB;AACzC;AAEA,MAAM,oBAA2C,CAAC;AAClD,MAAM,iBAA2C,CAAC;AAE3C,SAAS,cAAc,IAAoC;AAChE,QAAM,cAAc,eAAe;AACnC,SAAO,QAAQ,MAAM,YAAY,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC;AAC9E;AAEO,SAAS,YAAY,cAAiD;AAC3E,QAAM,UAAU,WAAW;AAE3B,SAAO,QAAQ,MAAM;AACnB,QAAI,CAAC,QAAS,QAAO;AAErB,WAAO,eACH,iBAAiB,OAAO,CAAC,MAAM,EAAE,iBAAiB,YAAY,IAC9D;AAAA,EACN,GAAG,CAAC,cAAc,OAAO,CAAC;AAC5B;AAEO,SAAS,WAAW;AACzB,QAAM,UAAU,WAAW;AAC3B,SAAO,UAAU,gBAAgB,CAAC;AACpC;AAcO,SAAS,uBAAgC;AAC9C,QAAM,EAAE,KAAK,IAAI;AAAA,IAA2B,CAAC,gBAAgB;AAAA,IAAG,CAAC,SAC/D,WAAW,OAAO,IAAI;AAAA,EACxB;AAEA,SAAO,MAAM,cAAc;AAC7B;AAEA,MAAM,mBAA+C,CAAC;AAe/C,SAAS,eACd,MACA,IASA,WAC0B;AAC1B,QAAM,UAAU,WAAW;AAE3B,QAAM,cAAc,SAAS;AAE7B,QAAM,MAAM,cAAc,YAAY;AAQtC,QAAM,EAAE,KAAK,IAAI;AAAA,IACf,CAAC,sBAAsB,MAAM,OAAO,EAAE;AAAA,IACtC,CAAC,SACC,kBAAkB,SAAS,MAAM;AAAA,MAC/B,OAAO;AAAA,MACP,GAAI,cAAc,EAAE,WAAW,IAAI,IAAI,EAAE,WAAW,IAAI;AAAA,IAC1D,CAAC;AAAA,IACH,EAAE,SAAS,CAAC,WAAW,QAAQ,GAAG,EAAE;AAAA,EACtC;AAEA,SAAO,QAAQ,MAAM;AACnB,QAAI,SAAS;AACX,UAAI,CAAC,GAAI,QAAO;AAEhB,aAAO,iBAAiB;AAAA,QACtB,CAAC,YACC,QAAQ,SAAS,SAAS,QAAQ,QAAQ,QAAQ,OAAO;AAAA,MAC7D,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,WAAW,cAAc,EAAE,UAAU,CAAC;AAAA,IAC3D;AAEA,UAAM,QAAQ,MAAM,SAAS,CAAC;AAK9B,WAAO,MACJ,IAAI,qBAAqB,EACzB,KAAK,CAAC,GAAG,MAAM,EAAE,WAAW,cAAc,EAAE,UAAU,CAAC;AAAA,EAC5D,GAAG,CAAC,MAAM,IAAI,MAAM,OAAO,CAAC;AAC9B;AAUO,SAAS,gBAA4C;AAC1D,QAAM,UAAU,WAAW;AAC3B,SAAO,UAAU,qBAAqB;AACxC;","names":[]}

package/dist/connect.d.ts

@@ -0,0 +1 @@
+export * from './connect/index';

package/dist/connect.js

@@ -0,0 +1 @@
+export * from './connect/index.js';

package/dist/converted-tag.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The tag "Mark converted" puts on a lead's customer and on the lead
+ * (`POST /inquiries/:id/convert`). Matched without case, since a merchant can
+ * type the same word by hand.
+ */
+export declare const CONVERTED_TAG = "Converted";
+export declare function hasConvertedTag(tags: readonly string[] | null | undefined): boolean;

package/dist/converted-tag.js

@@ -0,0 +1,9 @@
+const CONVERTED_TAG = "Converted";
+function hasConvertedTag(tags) {
+  return (tags ?? []).some((t) => t.toLowerCase() === CONVERTED_TAG.toLowerCase());
+}
+export {
+  CONVERTED_TAG,
+  hasConvertedTag
+};
+//# sourceMappingURL=converted-tag.js.map

package/dist/converted-tag.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/converted-tag.ts"],"sourcesContent":["/**\n * The tag \"Mark converted\" puts on a lead's customer and on the lead\n * (`POST /inquiries/:id/convert`). Matched without case, since a merchant can\n * type the same word by hand.\n */\nexport const CONVERTED_TAG = 'Converted';\n\nexport function hasConvertedTag(tags: readonly string[] | null | undefined): boolean {\n  return (tags ?? []).some((t) => t.toLowerCase() === CONVERTED_TAG.toLowerCase());\n}\n"],"mappings":"AAKO,MAAM,gBAAgB;AAEtB,SAAS,gBAAgB,MAAqD;AACnF,UAAQ,QAAQ,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,YAAY,MAAM,cAAc,YAAY,CAAC;AACjF;","names":[]}

package/dist/countries.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Country list for business setup. Full sovereign-state list (name + ISO 3166-1
+ * alpha-2 code) so no merchant is missing and we can show flags. The searchable
+ * Select makes the length a non-issue. Africa-first default is a call-site choice
+ * (Nigeria), not a reordering here.
+ */
+export interface Country {
+    name: string;
+    code: string;
+}
+export declare const COUNTRIES: readonly Country[];
+/** ISO alpha-2 → flag emoji via regional-indicator symbols. */
+export declare function flagEmoji(code: string): string;
+/**
+ * The currency a workspace gets when nobody has said which country it is in.
+ *
+ * NGN, and it mirrors ONE line: `input.currency || 'NGN'` in potter-api's
+ * `provision-tenant.usecase.ts`. That is where the default actually lives —
+ * the API applies it to every provisioning request that omits a currency — so
+ * anything the dashboard needs to SHOW before provisioning has to agree with
+ * it or the price quoted is not the price the workspace is created in.
+ *
+ * If that line ever changes, this one changes with it.
+ */
+export declare const DEFAULT_CURRENCY = "NGN";
+/**
+ * Primary currency for a country name, or null when the country is unknown.
+ *
+ * Null rather than a fallback, and that is the whole point of the change. This
+ * used to end `|| 'USD'`, which was wrong twice over:
+ *
+ * - It **overrode a correct default with an incorrect one.** The API already
+ *   answers a missing currency with NGN. By fabricating USD, the dashboard was
+ *   the only reason any workspace was ever created in dollars — 1 of 91 on the
+ *   development database, and every one of them a merchant who simply had not
+ *   picked a country yet.
+ * - It made the quoted price disagree with the workspace. `step-plan` prices
+ *   the plan off this, so somebody who had not chosen a country was quoted in
+ *   USD and then provisioned in NGN. The file next door carries a comment
+ *   warning against quoting "a merchant in Lagos a figure in pounds", and the
+ *   fallback was doing exactly that from a different direction.
+ *
+ * A caller that must display something uses `DEFAULT_CURRENCY`, so it shows
+ * what provisioning will really do. A caller that is SENDING a currency omits
+ * the field instead, and lets the one default decide.
+ */
+export declare function currencyForCountry(name: string): string | null;
+/** ISO code for a country name; undefined when unmapped. Used to bias geocoding. */
+export declare function codeForCountry(name: string): string | undefined;
+/**
+ * Where the business most likely operates.
+ *
+ * Time zone first, because it reflects location; the browser's language region
+ * second, because it is better than nothing; empty last, which leaves the field
+ * for the merchant to answer rather than answering it wrongly.
+ */
+export declare function countryForLocale(): string;
+/**
+ * Options for the Select: the value stays the plain country name (what we
+ * store), the label carries the flag so it shows in the field and the list.
+ */
+export declare const COUNTRY_OPTIONS: {
+    value: string;
+    label: string;
+}[];