arcy.js 0.0.2 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The three widget lifecycle events, and deliberately only three
+ * (PRODUCT_SCOPE §1.1, ADR 0050).
+ *
+ * `message` and the flow events are absent on purpose: they belong to
+ * subsystems that do not exist yet, and publishing an event name promises a
+ * contract before the thing that fires it is built. A host app that wires a
+ * handler and gets silence has been lied to. Adding an event later is additive.
+ */
+type ArcyEvent = "ready" | "open" | "close";
+type ArcyEventHandler = () => void;
+/** The function `on()` hands back. Calling it removes that one handler. */
+type Unsubscribe = () => void;
+/**
+ * What an attribute value may be. Mirrors the five trait data types the backend
+ * registry accepts (PRODUCT_SCOPE §9.1.5), plus `null`, which clears the key
+ * and is the only value that does.
+ *
+ * Typing is enforced server-side against the declared trait, not here: the
+ * widget cannot know what an app has declared, and validating twice with one
+ * side guessing produces disagreements that are worse than no check at all.
+ */
+type AttributeValue = string | number | boolean | null | string[];
+type Attributes = Record<string, AttributeValue>;
+/**
+ * What a caller may hand `identify()`, and it is deliberately wider than what
+ * goes on the wire (ADR 0194).
+ *
+ * `undefined` means "nothing to send for this key": the key is dropped from the
+ * payload before it leaves the browser, silently, and never reaches the server.
+ * It exists because every auth SDK returns optional fields, so the line an
+ * operator naturally writes is `user_email: user.primaryEmailAddress?.emailAddress`,
+ * and a type that refuses it refuses the install snippet we publish.
+ *
+ * This keeps the three spellings distinct. An absent key means "do not touch",
+ * `null` means "clear it", and a value means "set it". `undefined` is the first
+ * of those, spelled the way JavaScript spells it.
+ */
+type AttributesInput = Record<string, AttributeValue | undefined>;
+/**
+ * The complete set of `init()` options, and it is complete by design
+ * (PRODUCT_SCOPE §11.5.1, resolved at G1 as Q41). **Reopened once, D733**
+ * (PRD 11, slice 11.8): `contentLocale` was added as the fourth and only
+ * other deliberate exception, for the same reason as the original three - it
+ * is a runtime escape hatch the dashboard cannot know about, not
+ * configuration moved to the wrong side of the boundary. See `contentLocale`
+ * below for why it is a separate option from `locale` rather than a second
+ * code shape on the same one.
+ *
+ * Configuration is authored in the dashboard. These four are runtime escape
+ * hatches for things the dashboard structurally cannot know, and the dashboard
+ * shows an "Overridden in code" badge when one is sent. Anything a
+ * non-developer would want to change belongs in the dashboard, where they can
+ * actually reach it. **Do not add a fifth without reopening Q41.**
+ */
+interface ArcyOptions {
+    /** Consent signal for behavioral telemetry. A cookie banner is code. */
+    telemetry?: boolean;
+    /**
+     * Where the widget talks to ARCY, if not `https://api.arcyai.com`.
+     *
+     * The fifth escape hatch (D1396, ADR 0186), and it exists for one reason:
+     * a page under a Content Security Policy has to name every origin the
+     * widget reaches, and a customer who would rather name none can rewrite a
+     * path on their own domain to our API and pass it here. Session, chat,
+     * flows, telemetry, image uploads and the panel's web fonts all follow it,
+     * so proxying moves the whole widget rather than most of it.
+     *
+     * An origin or an origin with a path prefix, no trailing slash, for
+     * example `https://example.com/_arcy`. Anything that is not a string is
+     * ignored with a warning, like every other bad option.
+     */
+    apiBase?: string;
+    /**
+     * The host app usually knows the user's language before ARCY loads.
+     *
+     * Two-letter codes only (`"en"`/`"tr"`). This feeds `SdkApp.uiLanguage`,
+     * the agent's default reply-language directive (D691) - it does **not**
+     * set the session's content locale. See `contentLocale` for that, a
+     * deliberately separate option (D732, D733): the two shapes (`"en"` vs.
+     * `"en-US"`) are ambiguous on one option, and a customer whose
+     * reply-language default and content locale genuinely differ (an
+     * English-replying agent serving a `tr-TR` audience, or vice versa) needs
+     * to be able to set them independently.
+     */
+    locale?: string;
+    /** A support page wanting the panel open on arrival is a real, narrow case. */
+    defaultOpen?: boolean;
+    /**
+     * The end user's content locale (PRD 11, slice 11.8; ADR 0049, D733).
+     *
+     * Region-qualified (`"en-US"`/`"tr-TR"`, the `LocaleCode` catalogue from
+     * the backend's `locale-catalog.ts`), unlike `locale` above. Seeds
+     * `SdkSession.localeCode`'s explicit tier at bootstrap time - the same
+     * tier a `locale_code` identify()/updateUser() trait fills (§1.1's install
+     * snippet). **Not auto-derived from `locale`, deliberately (D733):** that
+     * would silently guess a customer's audience region from their reply
+     * language, which is wrong exactly when the two are set independently for
+     * a real reason. Pass both when both are known; pass neither and the
+     * chain falls through to the browser language, then the app default.
+     */
+    contentLocale?: string;
+}
+/**
+ * The namespace object: `window.arcy` in the HTML build, the default export in
+ * the npm build. Both paths resolve to the same object so a call written
+ * against one behaves identically on the other.
+ *
+ * **No method throws and no promise rejects** (ADR 0050). Async methods resolve
+ * even on failure and report through a console warning. A rejected promise
+ * nobody awaited surfaces as an unhandled rejection inside the customer's error
+ * reporting, attributed to them, and the documented install snippet calls
+ * `identify()` with no `await`.
+ */
+/**
+ * The third argument to `identify()` (slice 6.3, D158).
+ *
+ * **An options object rather than a positional third parameter**, because
+ * ADR 0050 froze this API and a frozen API published on customer pages is
+ * exactly where positional arguments accumulate into
+ * `identify(id, traits, hash, null, true)` with no way to fix it. Four extra
+ * characters in the copy-paste recipe buys extensibility on the one surface
+ * that cannot be revised.
+ */
+interface IdentifyOptions {
+    /**
+     * `HMAC-SHA256(environment Secret, userId)`, computed on the customer's own
+     * server and never in the browser (PRD 6, D152).
+     *
+     * The name is Intercom's and Segment's, so the install recipe reads as
+     * familiar rather than novel. Optional, and strongly recommended: with
+     * identity verification off it is recorded and changes nothing, and with it
+     * on an unproven identity degrades to anonymous rather than being trusted.
+     */
+    userHash?: string;
+}
+interface Arcy {
+    init(token: string, options?: ArcyOptions): Promise<void>;
+    identify(userId: string, attributes?: AttributesInput, options?: IdentifyOptions): Promise<void>;
+    identifyAnonymous(attributes?: AttributesInput): Promise<void>;
+    updateUser(attributes?: AttributesInput): Promise<void>;
+    reset(): void;
+    open(): void;
+    close(): void;
+    on(event: ArcyEvent, handler: ArcyEventHandler): Unsubscribe;
+    readonly VERSION: string;
+}
+
+/**
+ * Kept as a plain literal rather than injected from package.json at build time,
+ * so the ESM, CJS, and IIFE builds all carry the same value with no build-time
+ * indirection. Bumped with the package version.
+ */
+declare const VERSION = "0.1.1";
+
+/**
+ * The namespace object, and the npm build's default export. `src/browser.ts`
+ * builds the same object for `window.arcy` on the script path.
+ *
+ * The two entry points differ in exactly one argument (ADR 0185): this one
+ * loads the chat panel, the flow engine and the picker with `import()`, so
+ * they become chunks in the customer's own build on the customer's own
+ * origin. The script build injects them from the CDN, which is the origin
+ * its install snippet already comes from. Nothing else about the two paths
+ * differs, and a call written against one behaves identically on the other.
+ */
+declare const arcy: Arcy;
+
+export { type Arcy, type ArcyEvent, type ArcyEventHandler, type ArcyOptions, type AttributeValue, type Attributes, type AttributesInput, type Unsubscribe, VERSION, arcy as default };