@signalsupport/sdk 0.0.0-stage → 0.7.1

package/dist/model.d.ts

@@ -0,0 +1,201 @@
+/**
+ * What a report means to the person who filed it.
+ *
+ * Signal's statuses are written for the team working the queue. A reporter
+ * needs the same facts from the other side of the table: "someone is reading
+ * it", not "triage"; "fixed, check it on your machine", not "resolved". Every
+ * rule here is pure and unit-tested, because a status machine enforced inside
+ * a click handler is a status machine with one path per button.
+ */
+export type SignalType = 'incident' | 'request' | 'feedback';
+export type Impact = 'extensive' | 'significant' | 'moderate' | 'minor';
+export type Urgency = 'critical' | 'high' | 'medium' | 'low';
+export type SignalStatus = 'triage' | 'open' | 'in_progress' | 'waiting_user' | 'fix_pending_release' | 'deferred' | 'resolved' | 'rejected' | 'under_review' | 'planned' | 'shipped' | 'declined';
+export type Tone = 'neutral' | 'accent' | 'info' | 'warn' | 'danger' | 'success';
+/** One of the reporter's own signals, as `GET /v1/reporter/signals` returns it. */
+export interface ReporterReport {
+    id: string;
+    ref: string;
+    type: SignalType;
+    subject: string;
+    body: string;
+    status: SignalStatus;
+    disposition: string | null;
+    fixed_in_version: string | null;
+    verified_at: string | null;
+    reopens: number;
+    source_context: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+    team_replies: number;
+    last_team_reply_at: string | null;
+    /**
+     * The first time somebody on the team opened it. Separate from `status`: a
+     * person looking is not a decision about the report. Absent from a Signal
+     * that predates it, so read as "not yet".
+     *
+     * Never WHO: the team speaks as one, as it does in its replies. Signal
+     * 0.14.0-alpha.1 briefly sent `read_by_name`; it is ignored if present.
+     */
+    read_at?: string | null;
+}
+export type ReporterEvent = {
+    kind: 'status';
+    from: SignalStatus | null;
+    to: SignalStatus;
+    at: string;
+    by: 'you' | 'team';
+} | {
+    kind: 'reply';
+    body: string;
+    at: string;
+    by: 'you' | 'team';
+    author_name: string;
+};
+/**
+ * One line of the conversation as the panel draws it: the server's timeline,
+ * plus the moment the team first read the report. The read is a field on the
+ * report rather than a timeline event, so a panel that predates it is not
+ * handed a kind it cannot draw.
+ */
+export type ThreadItem = ReporterEvent | {
+    kind: 'read';
+    at: string;
+    by: 'team';
+    name: string | null;
+};
+export interface ReporterReportDetail extends ReporterReport {
+    timeline: ReporterEvent[];
+    attached: {
+        screenshot: boolean;
+        system: boolean;
+        browser: boolean;
+        trail: boolean;
+        extra: boolean;
+    };
+}
+/**
+ * The stages a report walks through, as a person would describe them.
+ *
+ * ⚠ THE LAST STAGE IS THE REPORTER'S, AND DRAWING IT IS THE POINT. The anxiety
+ * behind every bug report is "does this go anywhere", so the path is shown
+ * before anything is filed and again on every report, with the final node
+ * belonging to the person reading it.
+ */
+export declare const DEFECT_STAGES: readonly ["Sent", "Read", "Accepted", "Fixed", "You check"];
+export declare const FEEDBACK_STAGES: readonly ["Sent", "Read", "Planned", "Shipped"];
+export interface StatusView {
+    /** Short, for a pill. */
+    label: string;
+    /** One sentence, written for the reporter: what this state means for THEM. */
+    blurb: string;
+    tone: Tone;
+    stages: readonly string[];
+    /** Index into `stages`. */
+    stage: number;
+    /** Work is happening at this stage right now, so its marker can pulse. */
+    active: boolean;
+    /** Left the happy path (not taken, duplicate). The rail stops rather than implying a fix. */
+    offPath: boolean;
+    /** Still able to change, from the reporter's point of view. */
+    open: boolean;
+    /** Something is waiting on the reporter. Only this badges. */
+    needsYou: boolean;
+}
+/**
+ * Compare two version strings, segment by segment.
+ *
+ * ⚠ A STRING COMPARE IS WRONG HERE AND WOULD LOOK RIGHT FOR A YEAR. "0.9.0"
+ * sorts above "0.24.0" lexically, so someone on 0.24.0 would be told to update
+ * to an older build, and the check would never appear on the reports already
+ * fixed for them. A missing segment reads as 0.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * May the reporter confirm the fix on the build they are running?
+ *
+ * ⚠ ONLY ONCE THEY ACTUALLY HAVE IT. A "yes, it works" given on the broken
+ * build is worse than none: afterwards it looks exactly like a real one. With
+ * no fixed version named, or no running version known, the reporter is the
+ * best judge, so they are asked.
+ */
+export declare function canVerify(r: ReporterReport, runningVersion?: string): boolean;
+/** Fixed, but the reporter is still on an older build. */
+export declare function awaitingUpdate(r: ReporterReport, runningVersion?: string): boolean;
+/**
+ * Whether the reporter may still take this report back. Not once it is
+ * closed, and not while its fix is on its way: by then the work is done and
+ * the useful next step is checking it.
+ */
+export declare function canWithdraw(r: ReporterReport): boolean;
+export declare function statusView(r: ReporterReport, runningVersion?: string): StatusView;
+/**
+ * The conversation in the order things happened, with the team's first read
+ * placed where it fell. Accepting a report usually follows reading it within
+ * minutes, and without this line the two arrive as one.
+ *
+ * A read recorded AFTER the team had already acted is left out: the action
+ * already said somebody looked, and "Accepted" followed by "Read" reads as
+ * nonsense. It happens to reports acted on before reads were recorded.
+ */
+export declare function threadOf(d: ReporterReportDetail): ThreadItem[];
+/** The read line, said from the reporter's side. */
+export declare function readWords(name: string | null): string;
+export type Severity = 'blocking' | 'major' | 'minor' | 'cosmetic';
+/**
+ * How much a problem is holding the reporter up, in their words, and what the
+ * team's queue needs from it. The team's priority is derived from impact and
+ * urgency on the server; a reporter is never asked for a priority, because
+ * every reporter would pick the top one.
+ */
+export declare const SEVERITY: Record<Severity, {
+    label: string;
+    hint: string;
+    tone: Tone;
+    impact: Impact;
+    urgency: Urgency;
+}>;
+export type FeedbackKind = 'idea' | 'praise' | 'confusing' | 'complaint';
+export declare const FEEDBACK_KINDS: Record<FeedbackKind, {
+    label: string;
+    hint: string;
+}>;
+export declare const MIN_DESCRIPTION = 12;
+/**
+ * Which field stops a report being sent, if any.
+ *
+ * Names the field rather than returning a boolean, because "Submit is disabled
+ * and I cannot see why" is the most common way a form wastes someone's time.
+ */
+export declare function validateIssue(d: {
+    what: string;
+    expected: string;
+}): {
+    field: 'what' | 'expected';
+    message: string;
+} | null;
+/** Open reports above closed ones whatever their age: the list exists to be acted on. */
+export declare function sortReports<T extends ReporterReport>(reports: readonly T[], runningVersion?: string): T[];
+/** "3m ago". One phrasing for every duration on the panel. */
+export declare function formatAgo(then: string | number, now?: number): string;
+/**
+ * One status move, said from the reporter's side.
+ *
+ * The same move reads differently depending on who made it and where it came
+ * from: the reporter's own filing is "you sent this", not "received by you";
+ * answering the team's question is "back with the team", not "accepted by you".
+ */
+export declare function eventWords(e: {
+    from: SignalStatus | null;
+    to: SignalStatus;
+    by: 'you' | 'team';
+}): string;
+/**
+ * A report's body as the parts it was written in: the SDK files "What
+ * happened" and "Expected instead" as labelled blocks, and other producers
+ * send free text, which comes back as one unlabelled part.
+ */
+export declare function reportParts(body: string): {
+    label: string | null;
+    text: string;
+}[];

package/dist/react.d.ts

@@ -0,0 +1,26 @@
+import { type SlotName, type SupportWidget, type WidgetConfig } from './widget/index.js';
+export type SignalSupportProps = Omit<WidgetConfig, 'key'> & {
+    /** The publishable key (`sig_pub_…`). Named `keyId` because `key` is React's. */
+    keyId?: string;
+    onReady?: (widget: SupportWidget) => void;
+    onAttention?: (count: number) => void;
+};
+/**
+ * Mount the panel for the life of the calling component. Configuration is
+ * read once; `context` is kept current on every render, because it is the
+ * part that changes as someone moves around the product.
+ */
+export declare function useSignalSupport(props: SignalSupportProps): SupportWidget | null;
+/**
+ * The element behind one of the panel's slots, for `createPortal`:
+ *
+ * ```tsx
+ * const slot = useSignalSlot(widget, 'home-top');
+ * return slot && createPortal(<StatusNotice />, slot);
+ * ```
+ *
+ * Your component renders in your tree, with your context and your CSS.
+ */
+export declare function useSignalSlot(widget: SupportWidget | null, name: SlotName): HTMLElement | null;
+/** The same, as a component that renders nothing of its own. */
+export declare function SignalSupport(props: SignalSupportProps): null;

package/dist/react.js

@@ -0,0 +1,2 @@
+import{t as e}from"./chunks/widget-Bxsz5StK.js";import{useEffect as t,useLayoutEffect as n,useMemo as r,useRef as i,useState as a}from"react";function o(r){let[o,s]=a(null),c=i(r);n(()=>{c.current=r}),t(()=>{let{keyId:t,onReady:n,onAttention:r,...i}=c.current,a=e({...i,key:t}),o=r?a.on(`attention`,e=>c.current.onAttention?.(e)):()=>{};return s(a),n?.(a),()=>{o(),a.destroy(),s(null)}},[]);let l=JSON.stringify(r.context??{});t(()=>{o&&r.context&&o.setContext(r.context)},[o,l]);let u=JSON.stringify(r.theme??null);return t(()=>{o&&r.theme&&o.setTheme(r.theme)},[o,u]),t(()=>{o&&r.css!==void 0&&o.setCss(r.css)},[o,r.css]),o}function s(e,t){return r(()=>e?e.slot(t):null,[e,t])}function c(e){return o(e),null}export{c as SignalSupport,s as useSignalSlot,o as useSignalSupport};
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","names":[],"sources":["../src/react.ts"],"sourcesContent":["/**\n * `@signalsupport/sdk/react` — the panel as a React hook or component.\n *\n * ```tsx\n * import { SignalSupport } from '@signalsupport/sdk/react';\n *\n * <SignalSupport\n *   keyId={process.env.NEXT_PUBLIC_SIGNAL_KEY_ID}\n *   session=\"/api/signal/session\"\n *   appVersion={version}\n *   context={{ area: 'Rigging', projectId }}\n *   theme={{ preset: 'studio' }}\n *   launcher={false}\n *   onReady={(w) => (supportRef.current = w)}\n * />\n * ```\n *\n * The panel is still the framework-free widget in its own Shadow DOM; this\n * only mounts it with the component and keeps its context current.\n */\nimport { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';\n\nimport { mountSupport, type SlotName, type SupportWidget, type WidgetConfig } from './widget/index.js';\n\nexport type SignalSupportProps = Omit<WidgetConfig, 'key'> & {\n  /** The publishable key (`sig_pub_…`). Named `keyId` because `key` is React's. */\n  keyId?: string;\n  onReady?: (widget: SupportWidget) => void;\n  onAttention?: (count: number) => void;\n};\n\n/**\n * Mount the panel for the life of the calling component. Configuration is\n * read once; `context` is kept current on every render, because it is the\n * part that changes as someone moves around the product.\n */\nexport function useSignalSupport(props: SignalSupportProps): SupportWidget | null {\n  const [widget, setWidget] = useState<SupportWidget | null>(null);\n  const latest = useRef(props);\n  // Never written during render: a concurrent render React throws away would\n  // leave the ref holding props that were never committed. A layout effect runs\n  // before the mount effect below, so that one still reads this render's props.\n  useLayoutEffect(() => {\n    latest.current = props;\n  });\n\n  useEffect(() => {\n    const { keyId, onReady, onAttention, ...rest } = latest.current;\n    const w = mountSupport({ ...rest, key: keyId });\n    const off = onAttention ? w.on('attention', (n) => latest.current.onAttention?.(n as number)) : () => {};\n    setWidget(w);\n    onReady?.(w);\n    return () => {\n      off();\n      w.destroy();\n      setWidget(null);\n    };\n  }, []);\n\n  const contextKey = JSON.stringify(props.context ?? {});\n  useEffect(() => {\n    if (widget && props.context) widget.setContext(props.context);\n  }, [widget, contextKey]);\n\n  const themeKey = JSON.stringify(props.theme ?? null);\n  useEffect(() => {\n    if (widget && props.theme) widget.setTheme(props.theme);\n  }, [widget, themeKey]);\n\n  useEffect(() => {\n    if (widget && props.css !== undefined) widget.setCss(props.css);\n  }, [widget, props.css]);\n\n  return widget;\n}\n\n/**\n * The element behind one of the panel's slots, for `createPortal`:\n *\n * ```tsx\n * const slot = useSignalSlot(widget, 'home-top');\n * return slot && createPortal(<StatusNotice />, slot);\n * ```\n *\n * Your component renders in your tree, with your context and your CSS.\n */\nexport function useSignalSlot(widget: SupportWidget | null, name: SlotName): HTMLElement | null {\n  return useMemo(() => (widget ? widget.slot(name) : null), [widget, name]);\n}\n\n/** The same, as a component that renders nothing of its own. */\nexport function SignalSupport(props: SignalSupportProps): null {\n  useSignalSupport(props);\n  return null;\n}\n"],"mappings":"8IAoCA,SAAgB,EAAiB,EAAiD,CAChF,GAAM,CAAC,EAAQ,GAAa,EAA+B,IAAI,EACzD,EAAS,EAAO,CAAK,EAI3B,MAAsB,CACpB,EAAO,QAAU,CACnB,CAAC,EAED,MAAgB,CACd,GAAM,CAAE,QAAO,UAAS,cAAa,GAAG,GAAS,EAAO,QAClD,EAAI,EAAa,CAAE,GAAG,EAAM,IAAK,CAAM,CAAC,EACxC,EAAM,EAAc,EAAE,GAAG,YAAc,GAAM,EAAO,QAAQ,cAAc,CAAW,CAAC,MAAU,CAAC,EAGvG,OAFA,EAAU,CAAC,EACX,IAAU,CAAC,MACE,CACX,EAAI,EACJ,EAAE,QAAQ,EACV,EAAU,IAAI,CAChB,CACF,EAAG,CAAC,CAAC,EAEL,IAAM,EAAa,KAAK,UAAU,EAAM,SAAW,CAAC,CAAC,EACrD,MAAgB,CACV,GAAU,EAAM,SAAS,EAAO,WAAW,EAAM,OAAO,CAC9D,EAAG,CAAC,EAAQ,CAAU,CAAC,EAEvB,IAAM,EAAW,KAAK,UAAU,EAAM,OAAS,IAAI,EASnD,OARA,MAAgB,CACV,GAAU,EAAM,OAAO,EAAO,SAAS,EAAM,KAAK,CACxD,EAAG,CAAC,EAAQ,CAAQ,CAAC,EAErB,MAAgB,CACV,GAAU,EAAM,MAAQ,IAAA,IAAW,EAAO,OAAO,EAAM,GAAG,CAChE,EAAG,CAAC,EAAQ,EAAM,GAAG,CAAC,EAEf,CACT,CAYA,SAAgB,EAAc,EAA8B,EAAoC,CAC9F,OAAO,MAAe,EAAS,EAAO,KAAK,CAAI,EAAI,KAAO,CAAC,EAAQ,CAAI,CAAC,CAC1E,CAGA,SAAgB,EAAc,EAAiC,CAE7D,OADA,EAAiB,CAAK,EACf,IACT"}

package/dist/reporter.d.ts

@@ -0,0 +1,14 @@
+import type { ReporterReport, ReporterReportDetail } from './model.js';
+import type { SessionCache } from './session.js';
+/**
+ * The reporter's own reports, through their session: list, read, reply, and
+ * say whether a fix works. Nothing here can reach anyone else's.
+ */
+export interface ReporterApi {
+    list(): Promise<ReporterReport[]>;
+    get(id: string): Promise<ReporterReportDetail>;
+    reply(id: string, body: string): Promise<ReporterReportDetail>;
+    verify(id: string, works: boolean, note?: string): Promise<ReporterReportDetail>;
+    withdraw(id: string, note?: string): Promise<ReporterReportDetail>;
+}
+export declare function createReporterApi(base: string, session: SessionCache, fetchImpl?: typeof fetch): ReporterApi;

package/dist/server.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `@signalsupport/sdk/server` — the part that runs on YOUR server.
+ *
+ * A reporter session lets a signed-in person's browser file reports as them,
+ * follow those reports, read the team's replies and confirm a fix, without the
+ * browser ever holding your secret key. Your server vouches for the person:
+ *
+ * ```ts
+ * // app/api/signal/session/route.ts (Next.js; any Fetch-style framework works)
+ * import { sessionHandler } from '@signalsupport/sdk/server';
+ *
+ * export const POST = sessionHandler({
+ *   secretKey: process.env.SIGNAL_KEY_SECRET!,
+ *   getUser: async (req) => {
+ *     const user = await currentUser(req);          // your own auth
+ *     return user && { id: user.id, name: user.name, email: user.email };
+ *   },
+ * });
+ * ```
+ *
+ * Then give the widget `session: '/api/signal/session'`.
+ */
+export interface ReporterIdentity {
+    /** Your product's id for this person. */
+    id: string;
+    name?: string;
+    email?: string;
+}
+export interface SessionOptions {
+    /** A secret key (`sig_live_…` or `sig_test_…`). Never a publishable key. */
+    secretKey: string;
+    apiBase?: string;
+    /** Seconds. Default one hour, at most a day. */
+    ttlSeconds?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface MintedSession {
+    token: string;
+    expires_at: string;
+}
+/** Mint a reporter session for one of your users. Server-side only. */
+export declare function createReporterSession(user: ReporterIdentity, options: SessionOptions): Promise<MintedSession>;
+export interface HandlerOptions extends SessionOptions {
+    /**
+     * Who is signed in, from your own auth. Return null for nobody: the handler
+     * answers 401 and the panel works anonymously.
+     */
+    getUser: (req: Request) => Promise<ReporterIdentity | null | undefined> | ReporterIdentity | null | undefined;
+}
+/**
+ * A ready-made route for any framework that speaks `Request` / `Response`:
+ * Next.js route handlers, Hono, Remix, SvelteKit, Bun, Deno, Workers.
+ */
+export declare function sessionHandler(options: HandlerOptions): (req: Request) => Promise<Response>;

package/dist/server.js

@@ -0,0 +1,2 @@
+import{i as e,n as t,r as n}from"./chunks/constants-ClGbEpjT.js";async function r(r,i){if(!i.secretKey)throw new t(`CONFIG`,`createReporterSession needs your secret key`);if(i.secretKey.startsWith(`sig_pub_`))throw new t(`CONFIG`,`a publishable key (sig_pub_) cannot vouch for a person. Use the secret key (sig_live_), on your server.`);let a=(i.apiBase??`https://signal-api.character.xyz`).replace(/\/+$/,``),o=i.fetchImpl??globalThis.fetch?.bind(globalThis);if(!o)throw new t(`CONFIG`,`no fetch is available; pass fetchImpl`);let s;try{s=await o(`${a}/v1/reporter-sessions`,{method:`POST`,headers:{"content-type":`application/json`,authorization:`Bearer ${i.secretKey}`},body:JSON.stringify({external_id:r.id,name:r.name,email:r.email,ttl_seconds:i.ttlSeconds})})}catch(t){throw e(a,t)}let c=await n(s);return{token:c.token,expires_at:c.expires_at}}function i(e){return async n=>{let i=(e,t)=>new Response(JSON.stringify(t),{status:e,headers:{"content-type":`application/json`,"cache-control":`no-store`}}),a;try{a=await e.getUser(n)}catch{a=null}if(!a?.id)return i(401,{error:{code:`UNAUTHENTICATED`,message:`nobody is signed in`}});try{return i(200,await r(a,e))}catch(e){return i(e instanceof t&&e.status?e.status:502,{error:{code:e instanceof t?e.code:`UPSTREAM`,message:e instanceof Error?e.message:String(e)}})}}}export{r as createReporterSession,i as sessionHandler};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["/**\n * `@signalsupport/sdk/server` — the part that runs on YOUR server.\n *\n * A reporter session lets a signed-in person's browser file reports as them,\n * follow those reports, read the team's replies and confirm a fix, without the\n * browser ever holding your secret key. Your server vouches for the person:\n *\n * ```ts\n * // app/api/signal/session/route.ts (Next.js; any Fetch-style framework works)\n * import { sessionHandler } from '@signalsupport/sdk/server';\n *\n * export const POST = sessionHandler({\n *   secretKey: process.env.SIGNAL_KEY_SECRET!,\n *   getUser: async (req) => {\n *     const user = await currentUser(req);          // your own auth\n *     return user && { id: user.id, name: user.name, email: user.email };\n *   },\n * });\n * ```\n *\n * Then give the widget `session: '/api/signal/session'`.\n */\n\nimport { DEFAULT_API_BASE } from './constants.js';\nimport { readEnvelope, transportError, SignalError } from './errors.js';\n\nexport interface ReporterIdentity {\n  /** Your product's id for this person. */\n  id: string;\n  name?: string;\n  email?: string;\n}\n\nexport interface SessionOptions {\n  /** A secret key (`sig_live_…` or `sig_test_…`). Never a publishable key. */\n  secretKey: string;\n  apiBase?: string;\n  /** Seconds. Default one hour, at most a day. */\n  ttlSeconds?: number;\n  fetchImpl?: typeof fetch;\n}\n\nexport interface MintedSession {\n  token: string;\n  expires_at: string;\n}\n\n/** Mint a reporter session for one of your users. Server-side only. */\nexport async function createReporterSession(\n  user: ReporterIdentity,\n  options: SessionOptions,\n): Promise<MintedSession> {\n  if (!options.secretKey) throw new SignalError('CONFIG', 'createReporterSession needs your secret key');\n  if (options.secretKey.startsWith('sig_pub_')) {\n    throw new SignalError(\n      'CONFIG',\n      'a publishable key (sig_pub_) cannot vouch for a person. Use the secret key (sig_live_), on your server.',\n    );\n  }\n  const base = (options.apiBase ?? DEFAULT_API_BASE).replace(/\\/+$/, '');\n  const f = options.fetchImpl ?? globalThis.fetch?.bind(globalThis);\n  if (!f) throw new SignalError('CONFIG', 'no fetch is available; pass fetchImpl');\n  let res: Response;\n  try {\n    res = await f(`${base}/v1/reporter-sessions`, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json', authorization: `Bearer ${options.secretKey}` },\n      body: JSON.stringify({\n        external_id: user.id,\n        name: user.name,\n        email: user.email,\n        ttl_seconds: options.ttlSeconds,\n      }),\n    });\n  } catch (cause) {\n    throw transportError(base, cause);\n  }\n  const data = await readEnvelope<MintedSession>(res);\n  return { token: data.token, expires_at: data.expires_at };\n}\n\nexport interface HandlerOptions extends SessionOptions {\n  /**\n   * Who is signed in, from your own auth. Return null for nobody: the handler\n   * answers 401 and the panel works anonymously.\n   */\n  getUser: (req: Request) => Promise<ReporterIdentity | null | undefined> | ReporterIdentity | null | undefined;\n}\n\n/**\n * A ready-made route for any framework that speaks `Request` / `Response`:\n * Next.js route handlers, Hono, Remix, SvelteKit, Bun, Deno, Workers.\n */\nexport function sessionHandler(options: HandlerOptions): (req: Request) => Promise<Response> {\n  return async (req) => {\n    const json = (status: number, body: unknown) =>\n      new Response(JSON.stringify(body), {\n        status,\n        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },\n      });\n    let user: ReporterIdentity | null | undefined;\n    try {\n      user = await options.getUser(req);\n    } catch {\n      user = null;\n    }\n    if (!user?.id) return json(401, { error: { code: 'UNAUTHENTICATED', message: 'nobody is signed in' } });\n    try {\n      return json(200, await createReporterSession(user, options));\n    } catch (e) {\n      const status = e instanceof SignalError && e.status ? e.status : 502;\n      return json(status, { error: { code: e instanceof SignalError ? e.code : 'UPSTREAM', message: e instanceof Error ? e.message : String(e) } });\n    }\n  };\n}\n"],"mappings":"iEAgDA,eAAsB,EACpB,EACA,EACwB,CACxB,GAAI,CAAC,EAAQ,UAAW,MAAM,IAAI,EAAY,SAAU,6CAA6C,EACrG,GAAI,EAAQ,UAAU,WAAW,UAAU,EACzC,MAAM,IAAI,EACR,SACA,yGACF,EAEF,IAAM,GAAQ,EAAQ,SAAA,mCAAA,CAA6B,QAAQ,OAAQ,EAAE,EAC/D,EAAI,EAAQ,WAAa,WAAW,OAAO,KAAK,UAAU,EAChE,GAAI,CAAC,EAAG,MAAM,IAAI,EAAY,SAAU,uCAAuC,EAC/E,IAAI,EACJ,GAAI,CACF,EAAM,MAAM,EAAE,GAAG,EAAK,uBAAwB,CAC5C,OAAQ,OACR,QAAS,CAAE,eAAgB,mBAAoB,cAAe,UAAU,EAAQ,WAAY,EAC5F,KAAM,KAAK,UAAU,CACnB,YAAa,EAAK,GAClB,KAAM,EAAK,KACX,MAAO,EAAK,MACZ,YAAa,EAAQ,UACvB,CAAC,CACH,CAAC,CACH,OAAS,EAAO,CACd,MAAM,EAAe,EAAM,CAAK,CAClC,CACA,IAAM,EAAO,MAAM,EAA4B,CAAG,EAClD,MAAO,CAAE,MAAO,EAAK,MAAO,WAAY,EAAK,UAAW,CAC1D,CAcA,SAAgB,EAAe,EAA8D,CAC3F,OAAO,KAAO,IAAQ,CACpB,IAAM,GAAQ,EAAgB,IAC5B,IAAI,SAAS,KAAK,UAAU,CAAI,EAAG,CACjC,SACA,QAAS,CAAE,eAAgB,mBAAoB,gBAAiB,UAAW,CAC7E,CAAC,EACC,EACJ,GAAI,CACF,EAAO,MAAM,EAAQ,QAAQ,CAAG,CAClC,MAAQ,CACN,EAAO,IACT,CACA,GAAI,CAAC,GAAM,GAAI,OAAO,EAAK,IAAK,CAAE,MAAO,CAAE,KAAM,kBAAmB,QAAS,qBAAsB,CAAE,CAAC,EACtG,GAAI,CACF,OAAO,EAAK,IAAK,MAAM,EAAsB,EAAM,CAAO,CAAC,CAC7D,OAAS,EAAG,CAEV,OAAO,EADQ,aAAa,GAAe,EAAE,OAAS,EAAE,OAAS,IAC7C,CAAE,MAAO,CAAE,KAAM,aAAa,EAAc,EAAE,KAAO,WAAY,QAAS,aAAa,MAAQ,EAAE,QAAU,OAAO,CAAC,CAAE,CAAE,CAAC,CAC9I,CACF,CACF"}

package/dist/session.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The reporter session: who this browser is reporting as.
+ *
+ * The product's SERVER mints it with the secret key (see `./server`) and hands
+ * it to the browser; the browser never sees the secret. The SDK asks for one
+ * when it first needs it, keeps it until a minute before it expires, and asks
+ * again once if the service says it is no longer valid.
+ */
+export interface SessionToken {
+    /** `rs_…` */
+    token: string;
+    /** ISO time. Without it the token is kept until the service refuses it. */
+    expires_at?: string;
+}
+/**
+ * Where a session comes from.
+ *
+ * - a URL on your own server (`'/api/signal/session'`): POSTed with the
+ *   browser's cookies, answering `{ token, expires_at }`. Anything other than
+ *   200 means "nobody is signed in", and the panel works anonymously.
+ * - a function returning the same, for apps that fetch it their own way.
+ */
+export type SessionSource = string | (() => Promise<SessionToken | string | null | undefined>);
+export interface SessionCache {
+    /** The current token, fetching one if needed. Null when nobody is signed in. */
+    get(force?: boolean): Promise<string | null>;
+    clear(): void;
+}
+export declare function createSessionCache(source: SessionSource | undefined, fetchImpl?: typeof fetch): SessionCache;