@storyshelf/core 0.3.2 → 0.5.4

package/dist/tracing.mjs

@@ -0,0 +1,63 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
+//#region src/tracing.ts
+/**
+* Internal span and propagation helpers over `@opentelemetry/api`.
+*
+* Not exported from the package surface (see `package.json` exports): other
+* packages use `@storyshelf/observability`. Without a configured provider
+* every helper is a cheap noop, so call sites need no enabled-checks and
+* the hermetic vitest suite stays network-free.
+*/
+/** Instrumentation scope for core spans. */
+const SCOPE = "storyshelf.core";
+/** W3C traceparent header name. */
+const TRACEPARENT_HEADER = "traceparent";
+/**
+* Run `fn` inside an internal span.
+*
+* On throw the span records the exception, is marked ERROR, and the error
+* is rethrown — mirroring the pino `{ err }` convention.
+*
+* @param name - Span name (`domain.operation`, never a high-cardinality value).
+* @param fn - Work to run with the span active.
+* @param attributes - Fixed span attributes.
+* @param parent - Parent context (defaults to the active context).
+* @returns Whatever `fn` returns.
+*/
+async function withSpan(name, fn, attributes, parent) {
+	return await trace.getTracer(SCOPE).startActiveSpan(name, {
+		kind: SpanKind.INTERNAL,
+		attributes
+	}, parent ?? context.active(), async (span) => {
+		try {
+			return await fn(span);
+		} catch (error) {
+			span.recordException(error instanceof Error ? error : String(error));
+			span.setStatus({ code: SpanStatusCode.ERROR });
+			throw error;
+		} finally {
+			span.end();
+		}
+	});
+}
+/**
+* Resolve the parent context from an inbound `traceparent` value.
+*
+* @param traceparent - W3C value from a queue payload; absent keeps context.
+* @returns The extracted remote context, or the active context when absent.
+*/
+function parentContext(traceparent) {
+	if (!traceparent) return context.active();
+	return propagation.extract(context.active(), { [TRACEPARENT_HEADER]: traceparent });
+}
+/** Inject the active span context into a mutable header record. */
+function injectTraceContext(headers) {
+	propagation.inject(context.active(), headers);
+}
+//#endregion
+export { injectTraceContext, parentContext, withSpan };
+
+//# sourceMappingURL=tracing.mjs.map

package/dist/tracing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.mjs","names":[],"sources":["../src/tracing.ts"],"sourcesContent":["/**\n * Internal span and propagation helpers over `@opentelemetry/api`.\n *\n * Not exported from the package surface (see `package.json` exports): other\n * packages use `@storyshelf/observability`. Without a configured provider\n * every helper is a cheap noop, so call sites need no enabled-checks and\n * the hermetic vitest suite stays network-free.\n */\nimport {\n  SpanKind,\n  SpanStatusCode,\n  context,\n  propagation,\n  trace,\n  type Attributes,\n  type Context,\n  type Span,\n} from \"@opentelemetry/api\";\n\n/** Instrumentation scope for core spans. */\nconst SCOPE = \"storyshelf.core\";\n\n/** W3C traceparent header name. */\nconst TRACEPARENT_HEADER = \"traceparent\";\n\n/**\n * Run `fn` inside an internal span.\n *\n * On throw the span records the exception, is marked ERROR, and the error\n * is rethrown — mirroring the pino `{ err }` convention.\n *\n * @param name - Span name (`domain.operation`, never a high-cardinality value).\n * @param fn - Work to run with the span active.\n * @param attributes - Fixed span attributes.\n * @param parent - Parent context (defaults to the active context).\n * @returns Whatever `fn` returns.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T>,\n  attributes?: Attributes,\n  parent?: Context,\n): Promise<T> {\n  const tracer = trace.getTracer(SCOPE);\n  return await tracer.startActiveSpan(\n    name,\n    { kind: SpanKind.INTERNAL, attributes },\n    parent ?? context.active(),\n    async (span) => {\n      try {\n        return await fn(span);\n      } catch (error) {\n        span.recordException(error instanceof Error ? error : String(error));\n        span.setStatus({ code: SpanStatusCode.ERROR });\n        throw error;\n      } finally {\n        span.end();\n      }\n    },\n  );\n}\n\n/**\n * Resolve the parent context from an inbound `traceparent` value.\n *\n * @param traceparent - W3C value from a queue payload; absent keeps context.\n * @returns The extracted remote context, or the active context when absent.\n */\nexport function parentContext(traceparent?: string): Context {\n  if (!traceparent) {\n    return context.active();\n  }\n  return propagation.extract(context.active(), { [TRACEPARENT_HEADER]: traceparent });\n}\n\n/** Inject the active span context into a mutable header record. */\nexport function injectTraceContext(headers: Record<string, string>): void {\n  propagation.inject(context.active(), headers);\n}\n\n/**\n * Read the current W3C `traceparent` value for queue payloads.\n *\n * @returns The header value, or undefined when no span is active.\n */\nexport function currentTraceparent(): string | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  return carrier[TRACEPARENT_HEADER];\n}\n"],"mappings":";;;;;;;;;;;;;;AAoBA,MAAM,QAAQ;;AAGd,MAAM,qBAAqB;;;;;;;;;;;;;AAc3B,eAAsB,SACpB,MACA,IACA,YACA,QACY;CAEZ,OAAO,MADQ,MAAM,UAAU,KACb,CAAC,CAAC,gBAClB,MACA;EAAE,MAAM,SAAS;EAAU;CAAW,GACtC,UAAU,QAAQ,OAAO,GACzB,OAAO,SAAS;EACd,IAAI;GACF,OAAO,MAAM,GAAG,IAAI;EACtB,SAAS,OAAO;GACd,KAAK,gBAAgB,iBAAiB,QAAQ,QAAQ,OAAO,KAAK,CAAC;GACnE,KAAK,UAAU,EAAE,MAAM,eAAe,MAAM,CAAC;GAC7C,MAAM;EACR,UAAU;GACR,KAAK,IAAI;EACX;CACF,CACF;AACF;;;;;;;AAQA,SAAgB,cAAc,aAA+B;CAC3D,IAAI,CAAC,aACH,OAAO,QAAQ,OAAO;CAExB,OAAO,YAAY,QAAQ,QAAQ,OAAO,GAAG,GAAG,qBAAqB,YAAY,CAAC;AACpF;;AAGA,SAAgB,mBAAmB,SAAuC;CACxE,YAAY,OAAO,QAAQ,OAAO,GAAG,OAAO;AAC9C"}

package/dist/types.d.mts

@@ -9,22 +9,55 @@ type BuildStatus = (typeof BUILD_STATUSES)[number];
 declare const SNAPSHOT_STATUSES: readonly ["pending", "new", "unchanged", "changed", "approved", "rejected"];
 /** Review status of a snapshot. */
 type SnapshotStatus = (typeof SNAPSHOT_STATUSES)[number];
-/** Build statuses eligible for retention purging. */
+/**
+ * Build statuses considered terminal for retention purging.
+ * Only builds that have finished review (`approved`, `rejected`, `failed`)
+ * are eligible for TTL-based cleanup; `pending`/`reviewing` builds are kept.
+ */
 declare const TERMINAL_BUILD_STATUSES: readonly BuildStatus[];
 /** All site-wide user roles. */
-declare const SITE_ROLES: readonly ["admin", "member"];
+declare const SITE_ROLES: readonly ["admin", "member", "viewer"];
 /** Site-wide role of a user. */
 type SiteRole = (typeof SITE_ROLES)[number];
+/** Shared session cookie name used by auth (ADR 0008). */
+declare const SESSION_COOKIE = "storyshelf_session";
+/** An authenticated user of the platform. */
+interface AuthUser {
+  /** User ID. */
+  id: string;
+  /** User email. */
+  email: string;
+  /** Display name. */
+  name: string;
+  /** Optional avatar URL. */
+  avatarUrl?: string;
+  /** Site-wide role. */
+  role: SiteRole;
+  /**
+   * Identity-provider group memberships (names or IDs, provider-dependent).
+   * Populated when the provider exposes group claims; absent otherwise.
+   * Drives group-to-role mapping at login.
+   */
+  groups?: string[];
+  /**
+   * Login method that minted this identity.
+   * Matches an engine login method id; absent for single-method deployments.
+   */
+  providerId?: string;
+}
 /** All per-project membership roles. */
 declare const PROJECT_ROLES: readonly ["admin", "approver", "developer", "viewer"];
 /** Per-project role of a member. */
 type ProjectRole = (typeof PROJECT_ROLES)[number];
 /** Label type keys seeded for every new project. */
 declare const SEEDED_LABEL_KEYS: readonly ["branch", "persistent", "pr", "mr", "jira", "linear", "figma", "custom"];
-/** Label type keys reserved for internal use. */
+/** Label type keys reserved for internal bookkeeping (cannot be created by users). */
 declare const RESERVED_LABEL_KEYS: readonly ["build"];
-/** Label key marking a build as exempt from retention purging. */
+/**
+ * Label key that marks a build as exempt from retention purging.
+ * Attach `persistent=true` to keep a build indefinitely, even after its TTL expires.
+ */
 declare const PERSISTENT_LABEL_KEY = "persistent";
 //#endregion
-export { BUILD_STATUSES, BuildStatus, PERSISTENT_LABEL_KEY, PROJECT_ROLES, ProjectRole, RESERVED_LABEL_KEYS, SEEDED_LABEL_KEYS, SITE_ROLES, SNAPSHOT_STATUSES, SiteRole, SnapshotStatus, TERMINAL_BUILD_STATUSES };
+export { AuthUser, BUILD_STATUSES, BuildStatus, PERSISTENT_LABEL_KEY, PROJECT_ROLES, ProjectRole, RESERVED_LABEL_KEYS, SEEDED_LABEL_KEYS, SESSION_COOKIE, SITE_ROLES, SNAPSHOT_STATUSES, SiteRole, SnapshotStatus, TERMINAL_BUILD_STATUSES };
 //# sourceMappingURL=types.d.mts.map

package/dist/types.mjs

@@ -21,14 +21,24 @@ const SNAPSHOT_STATUSES = [
 	"approved",
 	"rejected"
 ];
-/** Build statuses eligible for retention purging. */
+/**
+* Build statuses considered terminal for retention purging.
+* Only builds that have finished review (`approved`, `rejected`, `failed`)
+* are eligible for TTL-based cleanup; `pending`/`reviewing` builds are kept.
+*/
 const TERMINAL_BUILD_STATUSES = [
 	"approved",
 	"rejected",
 	"failed"
 ];
 /** All site-wide user roles. */
-const SITE_ROLES = ["admin", "member"];
+const SITE_ROLES = [
+	"admin",
+	"member",
+	"viewer"
+];
+/** Shared session cookie name used by auth (ADR 0008). */
+const SESSION_COOKIE = "storyshelf_session";
 /** All per-project membership roles. */
 const PROJECT_ROLES = [
 	"admin",
@@ -47,11 +57,14 @@ const SEEDED_LABEL_KEYS = [
 	"figma",
 	"custom"
 ];
-/** Label type keys reserved for internal use. */
+/** Label type keys reserved for internal bookkeeping (cannot be created by users). */
 const RESERVED_LABEL_KEYS = ["build"];
-/** Label key marking a build as exempt from retention purging. */
+/**
+* Label key that marks a build as exempt from retention purging.
+* Attach `persistent=true` to keep a build indefinitely, even after its TTL expires.
+*/
 const PERSISTENT_LABEL_KEY = "persistent";
 //#endregion
-export { BUILD_STATUSES, PERSISTENT_LABEL_KEY, PROJECT_ROLES, RESERVED_LABEL_KEYS, SEEDED_LABEL_KEYS, SITE_ROLES, SNAPSHOT_STATUSES, TERMINAL_BUILD_STATUSES };
+export { BUILD_STATUSES, PERSISTENT_LABEL_KEY, PROJECT_ROLES, RESERVED_LABEL_KEYS, SEEDED_LABEL_KEYS, SESSION_COOKIE, SITE_ROLES, SNAPSHOT_STATUSES, TERMINAL_BUILD_STATUSES };
 
 //# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","names":[],"sources":["../src/types.ts"],"sourcesContent":["/** All lifecycle statuses a build can carry. */\nexport const BUILD_STATUSES = [\n  \"pending\",\n  \"capturing\",\n  \"comparing\",\n  \"reviewing\",\n  \"approved\",\n  \"rejected\",\n  \"failed\",\n] as const;\n\n/** Lifecycle status of a build. */\nexport type BuildStatus = (typeof BUILD_STATUSES)[number];\n\n/** All review statuses a snapshot can carry. */\nexport const SNAPSHOT_STATUSES = [\n  \"pending\",\n  \"new\",\n  \"unchanged\",\n  \"changed\",\n  \"approved\",\n  \"rejected\",\n] as const;\n\n/** Review status of a snapshot. */\nexport type SnapshotStatus = (typeof SNAPSHOT_STATUSES)[number];\n\n/** Build statuses eligible for retention purging. */\nexport const TERMINAL_BUILD_STATUSES: readonly BuildStatus[] = [\"approved\", \"rejected\", \"failed\"];\n\n/** All site-wide user roles. */\nexport const SITE_ROLES = [\"admin\", \"member\"] as const;\n\n/** Site-wide role of a user. */\nexport type SiteRole = (typeof SITE_ROLES)[number];\n\n/** All per-project membership roles. */\nexport const PROJECT_ROLES = [\"admin\", \"approver\", \"developer\", \"viewer\"] as const;\n\n/** Per-project role of a member. */\nexport type ProjectRole = (typeof PROJECT_ROLES)[number];\n\n/** Label type keys seeded for every new project. */\nexport const SEEDED_LABEL_KEYS = [\n  \"branch\",\n  \"persistent\",\n  \"pr\",\n  \"mr\",\n  \"jira\",\n  \"linear\",\n  \"figma\",\n  \"custom\",\n] as const;\n\n/** Label type keys reserved for internal use. */\nexport const RESERVED_LABEL_KEYS = [\"build\"] as const;\n\n/** Label key marking a build as exempt from retention purging. */\nexport const PERSISTENT_LABEL_KEY = \"persistent\";\n"],"mappings":";;;;;AACA,MAAa,iBAAiB;CAC5B;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAMA,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;AACF;;AAMA,MAAa,0BAAkD;CAAC;CAAY;CAAY;AAAQ;;AAGhG,MAAa,aAAa,CAAC,SAAS,QAAQ;;AAM5C,MAAa,gBAAgB;CAAC;CAAS;CAAY;CAAa;AAAQ;;AAMxE,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,sBAAsB,CAAC,OAAO;;AAG3C,MAAa,uBAAuB"}
+{"version":3,"file":"types.mjs","names":[],"sources":["../src/types.ts"],"sourcesContent":["/** All lifecycle statuses a build can carry. */\nexport const BUILD_STATUSES = [\n  \"pending\",\n  \"capturing\",\n  \"comparing\",\n  \"reviewing\",\n  \"approved\",\n  \"rejected\",\n  \"failed\",\n] as const;\n\n/** Lifecycle status of a build. */\nexport type BuildStatus = (typeof BUILD_STATUSES)[number];\n\n/** All review statuses a snapshot can carry. */\nexport const SNAPSHOT_STATUSES = [\n  \"pending\",\n  \"new\",\n  \"unchanged\",\n  \"changed\",\n  \"approved\",\n  \"rejected\",\n] as const;\n\n/** Review status of a snapshot. */\nexport type SnapshotStatus = (typeof SNAPSHOT_STATUSES)[number];\n\n/**\n * Build statuses considered terminal for retention purging.\n * Only builds that have finished review (`approved`, `rejected`, `failed`)\n * are eligible for TTL-based cleanup; `pending`/`reviewing` builds are kept.\n */\nexport const TERMINAL_BUILD_STATUSES: readonly BuildStatus[] = [\"approved\", \"rejected\", \"failed\"];\n\n/** All site-wide user roles. */\nexport const SITE_ROLES = [\"admin\", \"member\", \"viewer\"] as const;\n\n/** Site-wide role of a user. */\nexport type SiteRole = (typeof SITE_ROLES)[number];\n\n/** Shared session cookie name used by auth (ADR 0008). */\nexport const SESSION_COOKIE = \"storyshelf_session\";\n\n/** An authenticated user of the platform. */\nexport interface AuthUser {\n  /** User ID. */\n  id: string;\n  /** User email. */\n  email: string;\n  /** Display name. */\n  name: string;\n  /** Optional avatar URL. */\n  avatarUrl?: string;\n  /** Site-wide role. */\n  role: SiteRole;\n  /**\n   * Identity-provider group memberships (names or IDs, provider-dependent).\n   * Populated when the provider exposes group claims; absent otherwise.\n   * Drives group-to-role mapping at login.\n   */\n  groups?: string[];\n  /**\n   * Login method that minted this identity.\n   * Matches an engine login method id; absent for single-method deployments.\n   */\n  providerId?: string;\n}\n\n/** All per-project membership roles. */\nexport const PROJECT_ROLES = [\"admin\", \"approver\", \"developer\", \"viewer\"] as const;\n\n/** Per-project role of a member. */\nexport type ProjectRole = (typeof PROJECT_ROLES)[number];\n\n/** Label type keys seeded for every new project. */\nexport const SEEDED_LABEL_KEYS = [\n  \"branch\",\n  \"persistent\",\n  \"pr\",\n  \"mr\",\n  \"jira\",\n  \"linear\",\n  \"figma\",\n  \"custom\",\n] as const;\n\n/** Label type keys reserved for internal bookkeeping (cannot be created by users). */\nexport const RESERVED_LABEL_KEYS = [\"build\"] as const;\n\n/**\n * Label key that marks a build as exempt from retention purging.\n * Attach `persistent=true` to keep a build indefinitely, even after its TTL expires.\n */\nexport const PERSISTENT_LABEL_KEY = \"persistent\";\n"],"mappings":";;;;;AACA,MAAa,iBAAiB;CAC5B;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAMA,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;AAUA,MAAa,0BAAkD;CAAC;CAAY;CAAY;AAAQ;;AAGhG,MAAa,aAAa;CAAC;CAAS;CAAU;AAAQ;;AAMtD,MAAa,iBAAiB;;AA4B9B,MAAa,gBAAgB;CAAC;CAAS;CAAY;CAAa;AAAQ;;AAMxE,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,sBAAsB,CAAC,OAAO;;;;;AAM3C,MAAa,uBAAuB"}

package/dist/urls.d.mts

@@ -4,15 +4,21 @@ import __tsdown_shims_url from 'node:url';
 /** Type-safe URL builder for project pages and published Storybooks. */
 interface UrlBuilder {
   projectsList(): string;
+  projects(): string;
   project(slug: string): string;
+  projectsNew(): string;
   buildsList(slug: string): string;
   build(slug: string, buildId: string): string;
+  buildDiff(slug: string, buildId: string): string;
+  library(slug: string): string;
+  jobs(slug: string): string;
   labels(slug: string): string;
   label(slug: string, key: string, value: string): string;
   storybook(slug: string): string;
   storybookLabel(slug: string, key: string, value: string): string;
   storybookBuild(slug: string, buildId: string): string;
   settings(slug: string): string;
+  short(id: string): string;
 }
 /**
  * Create a URL builder rooted at the given base URL.
@@ -22,6 +28,11 @@ interface UrlBuilder {
  * @returns The URL builder.
  */
 declare function createUrlBuilder(baseUrl: string, publishedBaseDomain?: string): UrlBuilder;
+/**
+ * Embeddable image URL check for IdP-supplied avatars: `https:` and
+ * app-relative paths only, so `javascript:`/`data:` payloads fall back.
+ */
+declare function safeImageUrl(value: string | undefined): string | null;
 //#endregion
-export { UrlBuilder, createUrlBuilder };
+export { UrlBuilder, createUrlBuilder, safeImageUrl };
 //# sourceMappingURL=urls.d.mts.map

package/dist/urls.mjs

@@ -12,19 +12,38 @@ import.meta.url;
 function createUrlBuilder(baseUrl, publishedBaseDomain) {
 	const root = baseUrl.replace(/\/+$/u, "");
 	return {
-		projectsList: () => root,
+		projectsList: () => root || "/",
+		projects: () => `${root}/projects`,
 		project: (slug) => `${root}/projects/${slug}`,
+		projectsNew: () => `${root}/projects/new`,
 		buildsList: (slug) => `${root}/projects/${slug}/builds`,
 		build: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}`,
+		buildDiff: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}/diff`,
+		library: (slug) => `${root}/projects/${slug}/library`,
+		jobs: (slug) => `${root}/projects/${slug}/jobs`,
 		labels: (slug) => `${root}/projects/${slug}/labels`,
 		label: (slug, key, value) => `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodeURI(value)}`,
 		storybook: (slug) => publishedBaseDomain ? `https://${slug}.${publishedBaseDomain}` : `${root}/projects/${slug}/storybook`,
 		storybookLabel: (slug, key, value) => `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodeURI(value)}`,
 		storybookBuild: (slug, buildId) => publishedBaseDomain ? `https://${buildId}.${slug}.${publishedBaseDomain}` : `${root}/projects/${slug}/storybook/build/${buildId}`,
-		settings: (slug) => `${root}/projects/${slug}/settings`
+		settings: (slug) => `${root}/projects/${slug}/settings`,
+		short: (id) => `${root}/_/${id}/`
 	};
 }
+/**
+* Embeddable image URL check for IdP-supplied avatars: `https:` and
+* app-relative paths only, so `javascript:`/`data:` payloads fall back.
+*/
+function safeImageUrl(value) {
+	if (!value) return null;
+	if (value.startsWith("/") && !value.startsWith("//")) return value;
+	try {
+		return new URL(value).protocol === "https:" ? value : null;
+	} catch {
+		return null;
+	}
+}
 //#endregion
-export { createUrlBuilder };
+export { createUrlBuilder, safeImageUrl };
 
 //# sourceMappingURL=urls.mjs.map

package/dist/urls.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"urls.mjs","names":[],"sources":["../src/urls.ts"],"sourcesContent":["/** Type-safe URL builder for project pages and published Storybooks. */\nexport interface UrlBuilder {\n  projectsList(): string;\n  project(slug: string): string;\n  buildsList(slug: string): string;\n  build(slug: string, buildId: string): string;\n  labels(slug: string): string;\n  label(slug: string, key: string, value: string): string;\n  storybook(slug: string): string;\n  storybookLabel(slug: string, key: string, value: string): string;\n  storybookBuild(slug: string, buildId: string): string;\n  settings(slug: string): string;\n}\n\n/**\n * Create a URL builder rooted at the given base URL.\n *\n * @param baseUrl - Public root URL of the shelf server.\n * @param publishedBaseDomain - Optional wildcard domain for published Storybooks.\n * @returns The URL builder.\n */\nexport function createUrlBuilder(baseUrl: string, publishedBaseDomain?: string): UrlBuilder {\n  const root = baseUrl.replace(/\\/+$/u, \"\");\n\n  return {\n    projectsList: () => root,\n    project: (slug) => `${root}/projects/${slug}`,\n    buildsList: (slug) => `${root}/projects/${slug}/builds`,\n    build: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}`,\n    labels: (slug) => `${root}/projects/${slug}/labels`,\n    label: (slug, key, value) =>\n      `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodeURI(value)}`,\n    storybook: (slug) =>\n      publishedBaseDomain\n        ? `https://${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook`,\n    storybookLabel: (slug, key, value) =>\n      `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodeURI(value)}`,\n    storybookBuild: (slug, buildId) =>\n      publishedBaseDomain\n        ? `https://${buildId}.${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook/build/${buildId}`,\n    settings: (slug) => `${root}/projects/${slug}/settings`,\n  };\n}\n"],"mappings":";;;;;;;;;;;AAqBA,SAAgB,iBAAiB,SAAiB,qBAA0C;CAC1F,MAAM,OAAO,QAAQ,QAAQ,SAAS,EAAE;CAExC,OAAO;EACL,oBAAoB;EACpB,UAAU,SAAS,GAAG,KAAK,YAAY;EACvC,aAAa,SAAS,GAAG,KAAK,YAAY,KAAK;EAC/C,QAAQ,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU;EAC7D,SAAS,SAAS,GAAG,KAAK,YAAY,KAAK;EAC3C,QAAQ,MAAM,KAAK,UACjB,GAAG,KAAK,YAAY,KAAK,UAAU,mBAAmB,GAAG,EAAE,GAAG,UAAU,KAAK;EAC/E,YAAY,SACV,sBACI,WAAW,KAAK,GAAG,wBACnB,GAAG,KAAK,YAAY,KAAK;EAC/B,iBAAiB,MAAM,KAAK,UAC1B,GAAG,KAAK,YAAY,KAAK,aAAa,mBAAmB,GAAG,EAAE,GAAG,UAAU,KAAK;EAClF,iBAAiB,MAAM,YACrB,sBACI,WAAW,QAAQ,GAAG,KAAK,GAAG,wBAC9B,GAAG,KAAK,YAAY,KAAK,mBAAmB;EAClD,WAAW,SAAS,GAAG,KAAK,YAAY,KAAK;CAC/C;AACF"}
+{"version":3,"file":"urls.mjs","names":[],"sources":["../src/urls.ts"],"sourcesContent":["/** Type-safe URL builder for project pages and published Storybooks. */\nexport interface UrlBuilder {\n  projectsList(): string;\n  projects(): string;\n  project(slug: string): string;\n  projectsNew(): string;\n  buildsList(slug: string): string;\n  build(slug: string, buildId: string): string;\n  buildDiff(slug: string, buildId: string): string;\n  library(slug: string): string;\n  jobs(slug: string): string;\n  labels(slug: string): string;\n  label(slug: string, key: string, value: string): string;\n  storybook(slug: string): string;\n  storybookLabel(slug: string, key: string, value: string): string;\n  storybookBuild(slug: string, buildId: string): string;\n  settings(slug: string): string;\n  short(id: string): string;\n}\n\n/**\n * Create a URL builder rooted at the given base URL.\n *\n * @param baseUrl - Public root URL of the shelf server.\n * @param publishedBaseDomain - Optional wildcard domain for published Storybooks.\n * @returns The URL builder.\n */\nexport function createUrlBuilder(baseUrl: string, publishedBaseDomain?: string): UrlBuilder {\n  const root = baseUrl.replace(/\\/+$/u, \"\");\n\n  return {\n    projectsList: () => root || \"/\",\n    projects: () => `${root}/projects`,\n    project: (slug) => `${root}/projects/${slug}`,\n    projectsNew: () => `${root}/projects/new`,\n    buildsList: (slug) => `${root}/projects/${slug}/builds`,\n    build: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}`,\n    buildDiff: (slug, buildId) => `${root}/projects/${slug}/builds/${buildId}/diff`,\n    library: (slug) => `${root}/projects/${slug}/library`,\n    jobs: (slug) => `${root}/projects/${slug}/jobs`,\n    labels: (slug) => `${root}/projects/${slug}/labels`,\n    label: (slug, key, value) =>\n      `${root}/projects/${slug}/labels/${encodeURIComponent(key)}/${encodeURI(value)}`,\n    storybook: (slug) =>\n      publishedBaseDomain\n        ? `https://${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook`,\n    storybookLabel: (slug, key, value) =>\n      `${root}/projects/${slug}/storybook/${encodeURIComponent(key)}/${encodeURI(value)}`,\n    storybookBuild: (slug, buildId) =>\n      publishedBaseDomain\n        ? `https://${buildId}.${slug}.${publishedBaseDomain}`\n        : `${root}/projects/${slug}/storybook/build/${buildId}`,\n    settings: (slug) => `${root}/projects/${slug}/settings`,\n    short: (id) => `${root}/_/${id}/`,\n  };\n}\n\n/**\n * Embeddable image URL check for IdP-supplied avatars: `https:` and\n * app-relative paths only, so `javascript:`/`data:` payloads fall back.\n */\nexport function safeImageUrl(value: string | undefined): string | null {\n  if (!value) {\n    return null;\n  }\n  if (value.startsWith(\"/\") && !value.startsWith(\"//\")) {\n    return value;\n  }\n  try {\n    const url = new URL(value);\n    return url.protocol === \"https:\" ? value : null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;;;;AA2BA,SAAgB,iBAAiB,SAAiB,qBAA0C;CAC1F,MAAM,OAAO,QAAQ,QAAQ,SAAS,EAAE;CAExC,OAAO;EACL,oBAAoB,QAAQ;EAC5B,gBAAgB,GAAG,KAAK;EACxB,UAAU,SAAS,GAAG,KAAK,YAAY;EACvC,mBAAmB,GAAG,KAAK;EAC3B,aAAa,SAAS,GAAG,KAAK,YAAY,KAAK;EAC/C,QAAQ,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU;EAC7D,YAAY,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,UAAU,QAAQ;EACzE,UAAU,SAAS,GAAG,KAAK,YAAY,KAAK;EAC5C,OAAO,SAAS,GAAG,KAAK,YAAY,KAAK;EACzC,SAAS,SAAS,GAAG,KAAK,YAAY,KAAK;EAC3C,QAAQ,MAAM,KAAK,UACjB,GAAG,KAAK,YAAY,KAAK,UAAU,mBAAmB,GAAG,EAAE,GAAG,UAAU,KAAK;EAC/E,YAAY,SACV,sBACI,WAAW,KAAK,GAAG,wBACnB,GAAG,KAAK,YAAY,KAAK;EAC/B,iBAAiB,MAAM,KAAK,UAC1B,GAAG,KAAK,YAAY,KAAK,aAAa,mBAAmB,GAAG,EAAE,GAAG,UAAU,KAAK;EAClF,iBAAiB,MAAM,YACrB,sBACI,WAAW,QAAQ,GAAG,KAAK,GAAG,wBAC9B,GAAG,KAAK,YAAY,KAAK,mBAAmB;EAClD,WAAW,SAAS,GAAG,KAAK,YAAY,KAAK;EAC7C,QAAQ,OAAO,GAAG,KAAK,KAAK,GAAG;CACjC;AACF;;;;;AAMA,SAAgB,aAAa,OAA0C;CACrE,IAAI,CAAC,OACH,OAAO;CAET,IAAI,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,GACjD,OAAO;CAET,IAAI;EAEF,OAAO,IADS,IAAI,KACX,CAAC,CAAC,aAAa,WAAW,QAAQ;CAC7C,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/utils/encrypt.d.mts

@@ -0,0 +1,48 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/utils/encrypt.d.ts
+/** Current server secret plus the one it replaced, kept only to decrypt older rows. */
+interface SecretKeys {
+  current: string;
+  previous?: string;
+}
+/** What credential models accept: a bare secret, a rotation pair, or nothing. */
+type SecretInput = string | SecretKeys | undefined;
+/** Which key decrypted a payload. */
+type KeyUsed = "current" | "previous";
+/** Thrown when a stored credential cannot be decrypted with any configured key. */
+declare class UndecryptableCredentialError extends Error {
+  constructor(cause?: unknown);
+}
+/**
+ * Encrypt a plaintext secret for storage.
+ *
+ * Format: `base64url(iv):base64url(authTag):base64url(ciphertext)` (12B IV).
+ * Uses `secret` from `ShelfConfig.secret` — throws if missing so misconfiguration
+ * fails loudly like `scratchDir` does in `capture/orchestrator.ts`.
+ */
+declare function encrypt(input: SecretInput, plaintext: string): string;
+/**
+ * Decrypt a value produced by {@link encrypt}, trying the current key first and
+ * then the previous one (the rotation fallback).
+ *
+ * @param input - Server secret, or the current/previous pair during a rotation.
+ * @param ciphertext - Encrypted payload in `iv:tag:ciphertext` (base64url) format.
+ * @returns The original plaintext secret.
+ * @throws If no secret is configured, the payload is malformed, or no key decrypts it.
+ */
+declare function decrypt(input: SecretInput, ciphertext: string): string;
+/** Like {@link decrypt}, also reporting which key matched. */
+declare function decryptWithKey(input: SecretInput, ciphertext: string): {
+  plaintext: string;
+  keyUsed: KeyUsed;
+};
+/**
+ * Decrypt a stored credential, mapping any key mismatch or corruption to
+ * {@link UndecryptableCredentialError} so callers can fail loudly with a
+ * rotation hint. A missing secret keeps its own configuration error.
+ */
+declare function decryptCredential(input: SecretInput, ciphertext: string): string;
+//#endregion
+export { KeyUsed, SecretInput, SecretKeys, UndecryptableCredentialError, decrypt, decryptCredential, decryptWithKey, encrypt };
+//# sourceMappingURL=encrypt.d.mts.map

package/dist/utils/encrypt.mjs

@@ -3,14 +3,15 @@ import "node:url";
 import.meta.url;
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
 //#region src/utils/encrypt.ts
-/**
-* Derive a 32-byte AES-256 key from the server secret.
-*
-* Reuses the existing `sha256` pattern (`utils/hash.ts`) so key derivation
-* is consistent with token hashing and session HMAC.
-*/
-function deriveKey(secret) {
-	return createHash("sha256").update(secret).digest();
+/** Thrown when a stored credential cannot be decrypted with any configured key. */
+var UndecryptableCredentialError = class extends Error {
+	constructor(cause) {
+		super("Stored credential cannot be decrypted: check that SECRET (and SECRET_PREVIOUS after a rotation) match the key it was encrypted with", { cause });
+		this.name = "UndecryptableCredentialError";
+	}
+};
+function currentOf(secret) {
+	return typeof secret === "object" ? secret.current : secret;
 }
 /**
 * Encrypt a plaintext secret for storage.
@@ -19,7 +20,8 @@ function deriveKey(secret) {
 * Uses `secret` from `ShelfConfig.secret` — throws if missing so misconfiguration
 * fails loudly like `scratchDir` does in `capture/orchestrator.ts`.
 */
-function encrypt(secret, plaintext) {
+function encrypt(input, plaintext) {
+	const secret = currentOf(input);
 	if (!secret) throw new Error("Cannot encrypt: ShelfConfig.secret is not configured");
 	const key = deriveKey(secret);
 	const iv = randomBytes(12);
@@ -29,10 +31,53 @@ function encrypt(secret, plaintext) {
 	return `${iv.toString("base64url")}:${tag.toString("base64url")}:${enc.toString("base64url")}`;
 }
 /**
-* Decrypt a value produced by `encrypt`.
+* Decrypt a value produced by {@link encrypt}, trying the current key first and
+* then the previous one (the rotation fallback).
+*
+* @param input - Server secret, or the current/previous pair during a rotation.
+* @param ciphertext - Encrypted payload in `iv:tag:ciphertext` (base64url) format.
+* @returns The original plaintext secret.
+* @throws If no secret is configured, the payload is malformed, or no key decrypts it.
 */
-function decrypt(secret, ciphertext) {
-	if (!secret) throw new Error("Cannot decrypt: ShelfConfig.secret is not configured");
+function decrypt(input, ciphertext) {
+	return decryptWithKey(input, ciphertext).plaintext;
+}
+/** Like {@link decrypt}, also reporting which key matched. */
+function decryptWithKey(input, ciphertext) {
+	const current = currentOf(input);
+	if (!current) throw new Error("Cannot decrypt: ShelfConfig.secret is not configured");
+	try {
+		return {
+			plaintext: decryptWith(current, ciphertext),
+			keyUsed: "current"
+		};
+	} catch (error) {
+		const previous = typeof input === "object" ? input.previous : void 0;
+		if (!previous) throw error;
+		try {
+			return {
+				plaintext: decryptWith(previous, ciphertext),
+				keyUsed: "previous"
+			};
+		} catch {
+			throw error;
+		}
+	}
+}
+/**
+* Decrypt a stored credential, mapping any key mismatch or corruption to
+* {@link UndecryptableCredentialError} so callers can fail loudly with a
+* rotation hint. A missing secret keeps its own configuration error.
+*/
+function decryptCredential(input, ciphertext) {
+	if (!currentOf(input)) return decrypt(input, ciphertext);
+	try {
+		return decrypt(input, ciphertext);
+	} catch (error) {
+		throw new UndecryptableCredentialError(error);
+	}
+}
+function decryptWith(secret, ciphertext) {
 	const [ivB64, tagB64, encB64] = ciphertext.split(":");
 	if (!ivB64 || !tagB64 || !encB64) throw new Error("Invalid encrypted payload format");
 	const key = deriveKey(secret);
@@ -43,7 +88,16 @@ function decrypt(secret, ciphertext) {
 	decipher.setAuthTag(tag);
 	return Buffer.concat([decipher.update(enc), decipher.final()]).toString("utf8");
 }
+/**
+* Derive a 32-byte AES-256 key from the server secret.
+*
+* Reuses the existing `sha256` pattern (`utils/hash.ts`) so key derivation
+* is consistent with token hashing and session HMAC.
+*/
+function deriveKey(secret) {
+	return createHash("sha256").update(secret).digest();
+}
 //#endregion
-export { decrypt, encrypt };
+export { UndecryptableCredentialError, decrypt, decryptCredential, decryptWithKey, encrypt };
 
 //# sourceMappingURL=encrypt.mjs.map

package/dist/utils/encrypt.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"encrypt.mjs","names":[],"sources":["../../src/utils/encrypt.ts"],"sourcesContent":["import { createCipheriv, createDecipheriv, createHash, randomBytes } from \"node:crypto\";\n\n/**\n * Derive a 32-byte AES-256 key from the server secret.\n *\n * Reuses the existing `sha256` pattern (`utils/hash.ts`) so key derivation\n * is consistent with token hashing and session HMAC.\n */\nfunction deriveKey(secret: string): Buffer {\n  return createHash(\"sha256\").update(secret).digest();\n}\n\n/**\n * Encrypt a plaintext secret for storage.\n *\n * Format: `base64url(iv):base64url(authTag):base64url(ciphertext)` (12B IV).\n * Uses `secret` from `ShelfConfig.secret` — throws if missing so misconfiguration\n * fails loudly like `scratchDir` does in `capture/orchestrator.ts`.\n */\nexport function encrypt(secret: string | undefined, plaintext: string): string {\n  if (!secret) {\n    throw new Error(\"Cannot encrypt: ShelfConfig.secret is not configured\");\n  }\n  const key = deriveKey(secret);\n  const iv = randomBytes(12);\n  const cipher = createCipheriv(\"aes-256-gcm\", key, iv);\n  const enc = Buffer.concat([cipher.update(plaintext, \"utf8\"), cipher.final()]);\n  const tag = cipher.getAuthTag();\n  return `${iv.toString(\"base64url\")}:${tag.toString(\"base64url\")}:${enc.toString(\"base64url\")}`;\n}\n\n/**\n * Decrypt a value produced by `encrypt`.\n */\nexport function decrypt(secret: string | undefined, ciphertext: string): string {\n  if (!secret) {\n    throw new Error(\"Cannot decrypt: ShelfConfig.secret is not configured\");\n  }\n  const [ivB64, tagB64, encB64] = ciphertext.split(\":\");\n  if (!ivB64 || !tagB64 || !encB64) {\n    throw new Error(\"Invalid encrypted payload format\");\n  }\n  const key = deriveKey(secret);\n  const iv = Buffer.from(ivB64, \"base64url\");\n  const tag = Buffer.from(tagB64, \"base64url\");\n  const enc = Buffer.from(encB64, \"base64url\");\n  const decipher = createDecipheriv(\"aes-256-gcm\", key, iv);\n  decipher.setAuthTag(tag);\n  const dec = Buffer.concat([decipher.update(enc), decipher.final()]);\n  return dec.toString(\"utf8\");\n}\n"],"mappings":";;;;;;;;;;;AAQA,SAAS,UAAU,QAAwB;CACzC,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,OAAO;AACpD;;;;;;;;AASA,SAAgB,QAAQ,QAA4B,WAA2B;CAC7E,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,sDAAsD;CAExE,MAAM,MAAM,UAAU,MAAM;CAC5B,MAAM,KAAK,YAAY,EAAE;CACzB,MAAM,SAAS,eAAe,eAAe,KAAK,EAAE;CACpD,MAAM,MAAM,OAAO,OAAO,CAAC,OAAO,OAAO,WAAW,MAAM,GAAG,OAAO,MAAM,CAAC,CAAC;CAC5E,MAAM,MAAM,OAAO,WAAW;CAC9B,OAAO,GAAG,GAAG,SAAS,WAAW,EAAE,GAAG,IAAI,SAAS,WAAW,EAAE,GAAG,IAAI,SAAS,WAAW;AAC7F;;;;AAKA,SAAgB,QAAQ,QAA4B,YAA4B;CAC9E,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,sDAAsD;CAExE,MAAM,CAAC,OAAO,QAAQ,UAAU,WAAW,MAAM,GAAG;CACpD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,QACxB,MAAM,IAAI,MAAM,kCAAkC;CAEpD,MAAM,MAAM,UAAU,MAAM;CAC5B,MAAM,KAAK,OAAO,KAAK,OAAO,WAAW;CACzC,MAAM,MAAM,OAAO,KAAK,QAAQ,WAAW;CAC3C,MAAM,MAAM,OAAO,KAAK,QAAQ,WAAW;CAC3C,MAAM,WAAW,iBAAiB,eAAe,KAAK,EAAE;CACxD,SAAS,WAAW,GAAG;CAEvB,OADY,OAAO,OAAO,CAAC,SAAS,OAAO,GAAG,GAAG,SAAS,MAAM,CAAC,CACxD,CAAC,CAAC,SAAS,MAAM;AAC5B"}
+{"version":3,"file":"encrypt.mjs","names":[],"sources":["../../src/utils/encrypt.ts"],"sourcesContent":["import { createCipheriv, createDecipheriv, createHash, randomBytes } from \"node:crypto\";\n\n/** Current server secret plus the one it replaced, kept only to decrypt older rows. */\nexport interface SecretKeys {\n  current: string;\n  previous?: string;\n}\n\n/** What credential models accept: a bare secret, a rotation pair, or nothing. */\nexport type SecretInput = string | SecretKeys | undefined;\n\n/** Which key decrypted a payload. */\nexport type KeyUsed = \"current\" | \"previous\";\n\n/** Thrown when a stored credential cannot be decrypted with any configured key. */\nexport class UndecryptableCredentialError extends Error {\n  constructor(cause?: unknown) {\n    super(\n      \"Stored credential cannot be decrypted: check that SECRET (and SECRET_PREVIOUS after a rotation) match the key it was encrypted with\",\n      { cause },\n    );\n    this.name = \"UndecryptableCredentialError\";\n  }\n}\n\nfunction currentOf(secret: SecretInput): string | undefined {\n  return typeof secret === \"object\" ? secret.current : secret;\n}\n\n/**\n * Encrypt a plaintext secret for storage.\n *\n * Format: `base64url(iv):base64url(authTag):base64url(ciphertext)` (12B IV).\n * Uses `secret` from `ShelfConfig.secret` — throws if missing so misconfiguration\n * fails loudly like `scratchDir` does in `capture/orchestrator.ts`.\n */\nexport function encrypt(input: SecretInput, plaintext: string): string {\n  const secret = currentOf(input);\n  if (!secret) {\n    throw new Error(\"Cannot encrypt: ShelfConfig.secret is not configured\");\n  }\n  const key = deriveKey(secret);\n  const iv = randomBytes(12);\n  const cipher = createCipheriv(\"aes-256-gcm\", key, iv);\n  const enc = Buffer.concat([cipher.update(plaintext, \"utf8\"), cipher.final()]);\n  const tag = cipher.getAuthTag();\n  return `${iv.toString(\"base64url\")}:${tag.toString(\"base64url\")}:${enc.toString(\"base64url\")}`;\n}\n\n/**\n * Decrypt a value produced by {@link encrypt}, trying the current key first and\n * then the previous one (the rotation fallback).\n *\n * @param input - Server secret, or the current/previous pair during a rotation.\n * @param ciphertext - Encrypted payload in `iv:tag:ciphertext` (base64url) format.\n * @returns The original plaintext secret.\n * @throws If no secret is configured, the payload is malformed, or no key decrypts it.\n */\nexport function decrypt(input: SecretInput, ciphertext: string): string {\n  return decryptWithKey(input, ciphertext).plaintext;\n}\n\n/** Like {@link decrypt}, also reporting which key matched. */\nexport function decryptWithKey(\n  input: SecretInput,\n  ciphertext: string,\n): { plaintext: string; keyUsed: KeyUsed } {\n  const current = currentOf(input);\n  if (!current) {\n    throw new Error(\"Cannot decrypt: ShelfConfig.secret is not configured\");\n  }\n  try {\n    return { plaintext: decryptWith(current, ciphertext), keyUsed: \"current\" };\n  } catch (error) {\n    const previous = typeof input === \"object\" ? input.previous : undefined;\n    if (!previous) {\n      throw error;\n    }\n    try {\n      return { plaintext: decryptWith(previous, ciphertext), keyUsed: \"previous\" };\n    } catch {\n      throw error;\n    }\n  }\n}\n\n/**\n * Decrypt a stored credential, mapping any key mismatch or corruption to\n * {@link UndecryptableCredentialError} so callers can fail loudly with a\n * rotation hint. A missing secret keeps its own configuration error.\n */\nexport function decryptCredential(input: SecretInput, ciphertext: string): string {\n  if (!currentOf(input)) {\n    return decrypt(input, ciphertext);\n  }\n  try {\n    return decrypt(input, ciphertext);\n  } catch (error) {\n    throw new UndecryptableCredentialError(error);\n  }\n}\n\nfunction decryptWith(secret: string, ciphertext: string): string {\n  const [ivB64, tagB64, encB64] = ciphertext.split(\":\");\n  if (!ivB64 || !tagB64 || !encB64) {\n    throw new Error(\"Invalid encrypted payload format\");\n  }\n  const key = deriveKey(secret);\n  const iv = Buffer.from(ivB64, \"base64url\");\n  const tag = Buffer.from(tagB64, \"base64url\");\n  const enc = Buffer.from(encB64, \"base64url\");\n  const decipher = createDecipheriv(\"aes-256-gcm\", key, iv);\n  decipher.setAuthTag(tag);\n  const dec = Buffer.concat([decipher.update(enc), decipher.final()]);\n  return dec.toString(\"utf8\");\n}\n\n/**\n * Derive a 32-byte AES-256 key from the server secret.\n *\n * Reuses the existing `sha256` pattern (`utils/hash.ts`) so key derivation\n * is consistent with token hashing and session HMAC.\n */\nfunction deriveKey(secret: string): Buffer {\n  return createHash(\"sha256\").update(secret).digest();\n}\n"],"mappings":";;;;;;AAeA,IAAa,+BAAb,cAAkD,MAAM;CACtD,YAAY,OAAiB;EAC3B,MACE,uIACA,EAAE,MAAM,CACV;EACA,KAAK,OAAO;CACd;AACF;AAEA,SAAS,UAAU,QAAyC;CAC1D,OAAO,OAAO,WAAW,WAAW,OAAO,UAAU;AACvD;;;;;;;;AASA,SAAgB,QAAQ,OAAoB,WAA2B;CACrE,MAAM,SAAS,UAAU,KAAK;CAC9B,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,sDAAsD;CAExE,MAAM,MAAM,UAAU,MAAM;CAC5B,MAAM,KAAK,YAAY,EAAE;CACzB,MAAM,SAAS,eAAe,eAAe,KAAK,EAAE;CACpD,MAAM,MAAM,OAAO,OAAO,CAAC,OAAO,OAAO,WAAW,MAAM,GAAG,OAAO,MAAM,CAAC,CAAC;CAC5E,MAAM,MAAM,OAAO,WAAW;CAC9B,OAAO,GAAG,GAAG,SAAS,WAAW,EAAE,GAAG,IAAI,SAAS,WAAW,EAAE,GAAG,IAAI,SAAS,WAAW;AAC7F;;;;;;;;;;AAWA,SAAgB,QAAQ,OAAoB,YAA4B;CACtE,OAAO,eAAe,OAAO,UAAU,CAAC,CAAC;AAC3C;;AAGA,SAAgB,eACd,OACA,YACyC;CACzC,MAAM,UAAU,UAAU,KAAK;CAC/B,IAAI,CAAC,SACH,MAAM,IAAI,MAAM,sDAAsD;CAExE,IAAI;EACF,OAAO;GAAE,WAAW,YAAY,SAAS,UAAU;GAAG,SAAS;EAAU;CAC3E,SAAS,OAAO;EACd,MAAM,WAAW,OAAO,UAAU,WAAW,MAAM,WAAW,KAAA;EAC9D,IAAI,CAAC,UACH,MAAM;EAER,IAAI;GACF,OAAO;IAAE,WAAW,YAAY,UAAU,UAAU;IAAG,SAAS;GAAW;EAC7E,QAAQ;GACN,MAAM;EACR;CACF;AACF;;;;;;AAOA,SAAgB,kBAAkB,OAAoB,YAA4B;CAChF,IAAI,CAAC,UAAU,KAAK,GAClB,OAAO,QAAQ,OAAO,UAAU;CAElC,IAAI;EACF,OAAO,QAAQ,OAAO,UAAU;CAClC,SAAS,OAAO;EACd,MAAM,IAAI,6BAA6B,KAAK;CAC9C;AACF;AAEA,SAAS,YAAY,QAAgB,YAA4B;CAC/D,MAAM,CAAC,OAAO,QAAQ,UAAU,WAAW,MAAM,GAAG;CACpD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,QACxB,MAAM,IAAI,MAAM,kCAAkC;CAEpD,MAAM,MAAM,UAAU,MAAM;CAC5B,MAAM,KAAK,OAAO,KAAK,OAAO,WAAW;CACzC,MAAM,MAAM,OAAO,KAAK,QAAQ,WAAW;CAC3C,MAAM,MAAM,OAAO,KAAK,QAAQ,WAAW;CAC3C,MAAM,WAAW,iBAAiB,eAAe,KAAK,EAAE;CACxD,SAAS,WAAW,GAAG;CAEvB,OADY,OAAO,OAAO,CAAC,SAAS,OAAO,GAAG,GAAG,SAAS,MAAM,CAAC,CACxD,CAAC,CAAC,SAAS,MAAM;AAC5B;;;;;;;AAQA,SAAS,UAAU,QAAwB;CACzC,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,OAAO;AACpD"}

package/dist/utils/hash.d.mts

@@ -0,0 +1,17 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/utils/hash.d.ts
+/** Hash a value with SHA-256, returning lowercase hex. */
+declare function sha256(value: string): string;
+/** Sign a value with HMAC-SHA-256, returning lowercase hex. */
+declare function hmacSha256(secret: string, value: string): string;
+/** Generate a prefixed random token and its SHA-256 hash. */
+declare function randomToken(prefix: string): {
+  value: string;
+  hash: string;
+};
+/** Compare two strings in constant time to avoid timing leaks. */
+declare function timingSafeEqualString(a: string, b: string): boolean;
+//#endregion
+export { hmacSha256, randomToken, sha256, timingSafeEqualString };
+//# sourceMappingURL=hash.d.mts.map

package/dist/utils/hash.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { createHash, createHmac, randomBytes } from "node:crypto";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 //#region src/utils/hash.ts
 /** Hash a value with SHA-256, returning lowercase hex. */
 function sha256(value) {
@@ -19,7 +19,13 @@ function randomToken(prefix) {
 		hash: sha256(value)
 	};
 }
+/** Compare two strings in constant time to avoid timing leaks. */
+function timingSafeEqualString(a, b) {
+	const ab = Buffer.from(a);
+	const bb = Buffer.from(b);
+	return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
 //#endregion
-export { hmacSha256, randomToken, sha256 };
+export { hmacSha256, randomToken, sha256, timingSafeEqualString };
 
 //# sourceMappingURL=hash.mjs.map

package/dist/utils/hash.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"hash.mjs","names":[],"sources":["../../src/utils/hash.ts"],"sourcesContent":["import { createHash, createHmac, randomBytes, timingSafeEqual } from \"node:crypto\";\n\n/** Hash a value with SHA-256, returning lowercase hex. */\nexport function sha256(value: string): string {\n  return createHash(\"sha256\").update(value).digest(\"hex\");\n}\n\n/** Sign a value with HMAC-SHA-256, returning lowercase hex. */\nexport function hmacSha256(secret: string, value: string): string {\n  return createHmac(\"sha256\", secret).update(value).digest(\"hex\");\n}\n\n/** Generate a prefixed random token and its SHA-256 hash. */\nexport function randomToken(prefix: string): { value: string; hash: string } {\n  const value = `${prefix}${randomBytes(24).toString(\"base64url\")}`;\n  return { value, hash: sha256(value) };\n}\n\n/** Compare two strings in constant time to avoid timing leaks. */\nexport function timingSafeEqualString(a: string, b: string): boolean {\n  const ab = Buffer.from(a);\n  const bb = Buffer.from(b);\n  return ab.length === bb.length && timingSafeEqual(ab, bb);\n}\n"],"mappings":";;;;;;AAGA,SAAgB,OAAO,OAAuB;CAC5C,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK;AACxD;;AAGA,SAAgB,WAAW,QAAgB,OAAuB;CAChE,OAAO,WAAW,UAAU,MAAM,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK;AAChE;;AAGA,SAAgB,YAAY,QAAiD;CAC3E,MAAM,QAAQ,GAAG,SAAS,YAAY,EAAE,CAAC,CAAC,SAAS,WAAW;CAC9D,OAAO;EAAE;EAAO,MAAM,OAAO,KAAK;CAAE;AACtC"}
+{"version":3,"file":"hash.mjs","names":[],"sources":["../../src/utils/hash.ts"],"sourcesContent":["import { createHash, createHmac, randomBytes, timingSafeEqual } from \"node:crypto\";\n\n/** Hash a value with SHA-256, returning lowercase hex. */\nexport function sha256(value: string): string {\n  return createHash(\"sha256\").update(value).digest(\"hex\");\n}\n\n/** Sign a value with HMAC-SHA-256, returning lowercase hex. */\nexport function hmacSha256(secret: string, value: string): string {\n  return createHmac(\"sha256\", secret).update(value).digest(\"hex\");\n}\n\n/** Generate a prefixed random token and its SHA-256 hash. */\nexport function randomToken(prefix: string): { value: string; hash: string } {\n  const value = `${prefix}${randomBytes(24).toString(\"base64url\")}`;\n  return { value, hash: sha256(value) };\n}\n\n/** Compare two strings in constant time to avoid timing leaks. */\nexport function timingSafeEqualString(a: string, b: string): boolean {\n  const ab = Buffer.from(a);\n  const bb = Buffer.from(b);\n  return ab.length === bb.length && timingSafeEqual(ab, bb);\n}\n"],"mappings":";;;;;;AAGA,SAAgB,OAAO,OAAuB;CAC5C,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK;AACxD;;AAGA,SAAgB,WAAW,QAAgB,OAAuB;CAChE,OAAO,WAAW,UAAU,MAAM,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK;AAChE;;AAGA,SAAgB,YAAY,QAAiD;CAC3E,MAAM,QAAQ,GAAG,SAAS,YAAY,EAAE,CAAC,CAAC,SAAS,WAAW;CAC9D,OAAO;EAAE;EAAO,MAAM,OAAO,KAAK;CAAE;AACtC;;AAGA,SAAgB,sBAAsB,GAAW,GAAoB;CACnE,MAAM,KAAK,OAAO,KAAK,CAAC;CACxB,MAAM,KAAK,OAAO,KAAK,CAAC;CACxB,OAAO,GAAG,WAAW,GAAG,UAAU,gBAAgB,IAAI,EAAE;AAC1D"}

package/dist/utils/http.d.mts

@@ -0,0 +1,58 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../logger.mjs";
+//#region src/utils/http.d.ts
+/**
+ * Fetch JSON with timeout, retries, and structured errors.
+ *
+ * Retries network failures, 429, and 502/503/504 (honoring `Retry-After`);
+ * every other status throws {@link HttpError} immediately.
+ *
+ * @param url - Absolute request URL.
+ * @param options - Method, headers, JSON body, timeout, retries, logger.
+ * @returns The parsed JSON response body.
+ */
+declare function httpJson<T>(url: string, options?: HttpRequestOptions): Promise<T>;
+/**
+ * POST/PUT plain payloads (e.g. Slack/Teams webhook cards) with the same
+ * timeout, retry, and `Retry-After` semantics as {@link httpJson}.
+ *
+ * @param url - Absolute request URL.
+ * @param options - Method, headers, text body, timeout, retries, logger.
+ * @returns The raw response body text.
+ */
+declare function httpText(url: string, options?: HttpTextOptions): Promise<string>;
+/** Failed HTTP response: status code plus a snippet of the response body. */
+declare class HttpError extends Error {
+  readonly status: number;
+  readonly body: string;
+  readonly headers: Headers;
+  constructor(status: number, body: string, headers?: Headers);
+}
+/** Options for {@link httpJson}. */
+interface HttpRequestOptions {
+  method?: string;
+  headers?: Record<string, string>;
+  /** Body serialized as JSON with a `content-type` header. */
+  json?: unknown;
+  /** Per-attempt timeout in milliseconds (default 30s). */
+  timeoutMs?: number;
+  /** Total attempts including the first (default 3). */
+  retries?: number;
+  logger?: Logger;
+}
+/** Options for {@link httpText}. */
+interface HttpTextOptions {
+  method?: string;
+  headers?: Record<string, string>;
+  /** Body serialized as JSON with a `content-type` header. */
+  json?: unknown;
+  /** Per-attempt timeout in milliseconds (default 30s). */
+  timeoutMs?: number;
+  /** Total attempts including the first (default 3). */
+  retries?: number;
+  logger?: Logger;
+}
+//#endregion
+export { HttpError, HttpRequestOptions, HttpTextOptions, httpJson, httpText };
+//# sourceMappingURL=http.d.mts.map