@maravilla-labs/platform 0.1.36 → 0.1.39

package/dist/push.js

@@ -0,0 +1,141 @@
+// src/push.ts
+var DEFAULT_BASE_PATH = "/_platform/push";
+var DEFAULT_SW_PATH = "/_platform/push/sw.js";
+var VISITOR_STORAGE_KEY = "maravilla.push.visitorId";
+function assertPushSupported() {
+  if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) {
+    throw new Error("Web Push is not supported: serviceWorker is unavailable");
+  }
+  if (typeof window === "undefined" || !("PushManager" in window)) {
+    throw new Error("Web Push is not supported: PushManager is unavailable");
+  }
+}
+function base64UrlToArrayBuffer(input) {
+  const padding = "=".repeat((4 - input.length % 4) % 4);
+  const base64 = (input + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const raw = atob(base64);
+  const buffer = new ArrayBuffer(raw.length);
+  const view = new Uint8Array(buffer);
+  for (let i = 0; i < raw.length; i++) {
+    view[i] = raw.charCodeAt(i);
+  }
+  return buffer;
+}
+function arrayBufferToBase64Url(buffer) {
+  if (!buffer) return void 0;
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomUuid() {
+  const c = typeof crypto !== "undefined" ? crypto : void 0;
+  if (c && typeof c.randomUUID === "function") {
+    return c.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (c && typeof c.getRandomValues === "function") {
+    c.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function resolveVisitorId(userId, visitorId) {
+  if (visitorId) return visitorId;
+  if (userId) return null;
+  try {
+    const stored = window.localStorage.getItem(VISITOR_STORAGE_KEY);
+    if (stored) return stored;
+    const fresh = randomUuid();
+    window.localStorage.setItem(VISITOR_STORAGE_KEY, fresh);
+    return fresh;
+  } catch {
+    return randomUuid();
+  }
+}
+async function fetchVapidPublicKey(basePath) {
+  const res = await fetch(`${basePath}/vapid-public-key`, {
+    method: "GET",
+    credentials: "same-origin",
+    headers: { Accept: "application/json" }
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch VAPID public key: ${res.status} ${res.statusText}`);
+  }
+  const body = await res.json();
+  if (!body || typeof body.publicKey !== "string" || body.publicKey.length === 0) {
+    throw new Error("VAPID public key response is missing `publicKey`");
+  }
+  return body.publicKey;
+}
+function extractKeys(sub) {
+  return {
+    p256dh: arrayBufferToBase64Url(sub.getKey("p256dh")),
+    auth: arrayBufferToBase64Url(sub.getKey("auth"))
+  };
+}
+async function registerPush(opts = {}) {
+  assertPushSupported();
+  const basePath = opts.basePath ?? DEFAULT_BASE_PATH;
+  const swPath = opts.swPath ?? DEFAULT_SW_PATH;
+  const topics = opts.topics ?? [];
+  const userId = opts.userId ?? null;
+  const visitorId = resolveVisitorId(userId, opts.visitorId);
+  const publicKey = await fetchVapidPublicKey(basePath);
+  const registration = await navigator.serviceWorker.register(swPath);
+  await navigator.serviceWorker.ready;
+  const existing = await registration.pushManager.getSubscription();
+  const subscription = existing ?? await registration.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: base64UrlToArrayBuffer(publicKey)
+  });
+  const { p256dh, auth } = extractKeys(subscription);
+  const res = await fetch(`${basePath}/subscribe`, {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify({
+      provider: "web-push",
+      endpoint: subscription.endpoint,
+      p256dh,
+      auth,
+      userId,
+      visitorId,
+      topics
+    })
+  });
+  if (!res.ok) {
+    throw new Error(`Subscribe failed: ${res.status} ${res.statusText}`);
+  }
+  const saved = await res.json();
+  if (!saved || typeof saved.id !== "string" || saved.id.length === 0) {
+    throw new Error("Subscribe response is missing `id`");
+  }
+  return { subscription, subscriptionId: saved.id };
+}
+async function unregisterPush(subscriptionId, opts = {}) {
+  if (!subscriptionId) {
+    throw new Error("subscriptionId is required");
+  }
+  const basePath = opts.basePath ?? DEFAULT_BASE_PATH;
+  const res = await fetch(`${basePath}/unsubscribe`, {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ subscriptionId })
+  });
+  if (!res.ok && res.status !== 404) {
+    throw new Error(`Unsubscribe failed: ${res.status} ${res.statusText}`);
+  }
+}
+export {
+  registerPush,
+  unregisterPush
+};
+//# sourceMappingURL=push.js.map

package/dist/push.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/push.ts"],"sourcesContent":["/**\n * @fileoverview Web Push client SDK for Maravilla tenants.\n *\n * Talks to the tenant-origin `/_platform/push` endpoints served by delivery:\n *   - GET  /vapid-public-key  — fetch the VAPID public key for subscribe\n *   - POST /subscribe         — create a subscription\n *   - POST /unsubscribe       — delete a subscription by id (or endpoint)\n *\n * The matching service worker is served from `/_platform/push/sw.js` on the\n * same tenant origin (browsers require same-origin SW registration).\n */\n\nconst DEFAULT_BASE_PATH = '/_platform/push';\nconst DEFAULT_SW_PATH = '/_platform/push/sw.js';\nconst VISITOR_STORAGE_KEY = 'maravilla.push.visitorId';\n\nexport interface RegisterPushOptions {\n  /** Free-form topic strings to tag this subscription with. */\n  topics?: string[];\n  /** Authenticated user id, if any. Takes precedence over visitorId. */\n  userId?: string | null;\n  /** Anonymous visitor id. If omitted and userId is also omitted, one\n   *  is generated and persisted to localStorage under `maravilla.push.visitorId`. */\n  visitorId?: string | null;\n  /** Override the sw.js path (defaults to `/_platform/push/sw.js`). */\n  swPath?: string;\n  /** Override the API base path (defaults to `/_platform/push`). */\n  basePath?: string;\n}\n\nexport interface RegisterPushResult {\n  /** The browser PushSubscription (see Web Push spec). */\n  subscription: PushSubscription;\n  /** Server-issued subscription id — pass this back to unregisterPush. */\n  subscriptionId: string;\n}\n\ninterface VapidPublicKeyResponse {\n  publicKey: string;\n  contactEmail?: string;\n}\n\ninterface ServerSubscription {\n  id: string;\n  [key: string]: unknown;\n}\n\nfunction assertPushSupported(): void {\n  if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {\n    throw new Error('Web Push is not supported: serviceWorker is unavailable');\n  }\n  if (typeof window === 'undefined' || !('PushManager' in window)) {\n    throw new Error('Web Push is not supported: PushManager is unavailable');\n  }\n}\n\nfunction base64UrlToArrayBuffer(input: string): ArrayBuffer {\n  const padding = '='.repeat((4 - (input.length % 4)) % 4);\n  const base64 = (input + padding).replace(/-/g, '+').replace(/_/g, '/');\n  const raw = atob(base64);\n  const buffer = new ArrayBuffer(raw.length);\n  const view = new Uint8Array(buffer);\n  for (let i = 0; i < raw.length; i++) {\n    view[i] = raw.charCodeAt(i);\n  }\n  return buffer;\n}\n\nfunction arrayBufferToBase64Url(buffer: ArrayBuffer | null): string | undefined {\n  if (!buffer) return undefined;\n  const bytes = new Uint8Array(buffer);\n  let binary = '';\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n}\n\nfunction randomUuid(): string {\n  const c = typeof crypto !== 'undefined' ? crypto : undefined;\n  if (c && typeof c.randomUUID === 'function') {\n    return c.randomUUID();\n  }\n  const bytes = new Uint8Array(16);\n  if (c && typeof c.getRandomValues === 'function') {\n    c.getRandomValues(bytes);\n  } else {\n    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);\n  }\n  bytes[6] = (bytes[6] & 0x0f) | 0x40;\n  bytes[8] = (bytes[8] & 0x3f) | 0x80;\n  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');\n  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;\n}\n\nfunction resolveVisitorId(\n  userId: string | null | undefined,\n  visitorId: string | null | undefined,\n): string | null {\n  if (visitorId) return visitorId;\n  if (userId) return null;\n  try {\n    const stored = window.localStorage.getItem(VISITOR_STORAGE_KEY);\n    if (stored) return stored;\n    const fresh = randomUuid();\n    window.localStorage.setItem(VISITOR_STORAGE_KEY, fresh);\n    return fresh;\n  } catch {\n    return randomUuid();\n  }\n}\n\nasync function fetchVapidPublicKey(basePath: string): Promise<string> {\n  const res = await fetch(`${basePath}/vapid-public-key`, {\n    method: 'GET',\n    credentials: 'same-origin',\n    headers: { Accept: 'application/json' },\n  });\n  if (!res.ok) {\n    throw new Error(`Failed to fetch VAPID public key: ${res.status} ${res.statusText}`);\n  }\n  const body = (await res.json()) as VapidPublicKeyResponse;\n  if (!body || typeof body.publicKey !== 'string' || body.publicKey.length === 0) {\n    throw new Error('VAPID public key response is missing `publicKey`');\n  }\n  return body.publicKey;\n}\n\nfunction extractKeys(sub: PushSubscription): { p256dh?: string; auth?: string } {\n  return {\n    p256dh: arrayBufferToBase64Url(sub.getKey('p256dh')),\n    auth: arrayBufferToBase64Url(sub.getKey('auth')),\n  };\n}\n\nexport async function registerPush(\n  opts: RegisterPushOptions = {},\n): Promise<RegisterPushResult> {\n  assertPushSupported();\n\n  const basePath = opts.basePath ?? DEFAULT_BASE_PATH;\n  const swPath = opts.swPath ?? DEFAULT_SW_PATH;\n  const topics = opts.topics ?? [];\n  const userId = opts.userId ?? null;\n  const visitorId = resolveVisitorId(userId, opts.visitorId);\n\n  const publicKey = await fetchVapidPublicKey(basePath);\n  const registration = await navigator.serviceWorker.register(swPath);\n  await navigator.serviceWorker.ready;\n\n  const existing = await registration.pushManager.getSubscription();\n  const subscription =\n    existing ??\n    (await registration.pushManager.subscribe({\n      userVisibleOnly: true,\n      applicationServerKey: base64UrlToArrayBuffer(publicKey),\n    }));\n\n  const { p256dh, auth } = extractKeys(subscription);\n\n  const res = await fetch(`${basePath}/subscribe`, {\n    method: 'POST',\n    credentials: 'same-origin',\n    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },\n    body: JSON.stringify({\n      provider: 'web-push',\n      endpoint: subscription.endpoint,\n      p256dh,\n      auth,\n      userId,\n      visitorId,\n      topics,\n    }),\n  });\n\n  if (!res.ok) {\n    throw new Error(`Subscribe failed: ${res.status} ${res.statusText}`);\n  }\n\n  const saved = (await res.json()) as ServerSubscription;\n  if (!saved || typeof saved.id !== 'string' || saved.id.length === 0) {\n    throw new Error('Subscribe response is missing `id`');\n  }\n\n  return { subscription, subscriptionId: saved.id };\n}\n\nexport async function unregisterPush(\n  subscriptionId: string,\n  opts: { basePath?: string } = {},\n): Promise<void> {\n  if (!subscriptionId) {\n    throw new Error('subscriptionId is required');\n  }\n  const basePath = opts.basePath ?? DEFAULT_BASE_PATH;\n\n  const res = await fetch(`${basePath}/unsubscribe`, {\n    method: 'POST',\n    credentials: 'same-origin',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify({ subscriptionId }),\n  });\n\n  if (!res.ok && res.status !== 404) {\n    throw new Error(`Unsubscribe failed: ${res.status} ${res.statusText}`);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.1.36",
+  "version": "0.1.39",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./push": {
+      "types": "./dist/push.d.ts",
+      "import": "./dist/push.js"
     }
   },
   "scripts": {

package/src/config.ts

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.
+ *
+ * Declares your project's auth settings (resources, groups, relations,
+ * registration fields, OAuth providers, security policy, branding) alongside
+ * your code. The Maravilla adapter reads this at build time and reconciles
+ * the settings into delivery on deploy.
+ *
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [
+ *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],
+ *         policy: 'auth.user_id == node.owner' },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * Omitted sections leave the DB alone — partial adoption is explicitly
+ * supported. List-based sections (`resources`, `groups`, `relations`,
+ * `oauth`) are upserted and never auto-delete DB-only entries. Singleton
+ * sections (`registration`, `security`, `branding`) are replaced wholesale
+ * when declared.
+ */
+
+/**
+ * String value that may either be a literal secret or a reference to an
+ * environment variable on the **tenant** (resolved server-side at
+ * reconcile time, never shipped plaintext in the manifest).
+ *
+ * Accepted forms:
+ *   - `"literal-value"` — inline (not recommended for real secrets)
+ *   - `"${env.VAR_NAME}"` — string-template form
+ *   - `{ env: "VAR_NAME" }` — object form
+ */
+export type SecretRef = string | { env: string };
+
+// ── Resources + policies ──
+
+export interface ResourceDefinition {
+  /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */
+  name: string;
+  /** Human-readable title for the admin UI. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */
+  actions: string[];
+  /**
+   * Optional raisin-rel policy expression. Evaluated on every KV/DB/
+   * realtime/media op that targets this resource. Leave empty to skip
+   * Layer 2 for this resource — tenant + owner isolation still applies.
+   */
+  policy?: string;
+}
+
+// ── Groups ──
+
+export interface GroupPermissionDefinition {
+  /** Must match a `ResourceDefinition.name`. */
+  resource_name: string;
+  /** Actions this group is granted on the resource. */
+  actions: string[];
+}
+
+export interface GroupDefinition {
+  /** Unique group name per tenant. */
+  name: string;
+  /** Optional description for the admin UI. */
+  description?: string;
+  /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */
+  permissions?: GroupPermissionDefinition[];
+}
+
+// ── Relations ──
+
+export interface RelationTypeDefinition {
+  /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */
+  relation_name: string;
+  /** Human-readable title. */
+  title: string;
+  description?: string;
+  /** Grouping for the admin UI (e.g. `"family"`, `"work"`). */
+  category?: string;
+  icon?: string;
+  color?: string;
+  /** Name of the inverse relation type, if one exists. */
+  inverse_relation_name?: string;
+  /** When true, membership in this relation implies stewardship rights. */
+  implies_stewardship?: boolean;
+  /** When true, the relation can only target users flagged as minors. */
+  requires_minor?: boolean;
+  /** When true, the relation is symmetric (A→B implies B→A). */
+  bidirectional?: boolean;
+}
+
+// ── Registration fields ──
+
+export interface RegistrationFieldDefinition {
+  /** Field key used as the form field name + in profile data. */
+  key: string;
+  /** Display label. */
+  label: string;
+  /** One of: text, email, phone, date, number, select, boolean, url, textarea. */
+  field_type: string;
+  required: boolean;
+  show_on_register: boolean;
+  /** Optional validation metadata — passed through to the UI. */
+  validation?: Record<string, unknown>;
+}
+
+export interface RegistrationConfig {
+  /** Ordered list of custom registration fields. Declaring this replaces the full list. */
+  fields: RegistrationFieldDefinition[];
+}
+
+// ── OAuth providers ──
+
+export interface OAuthProviderDefinition {
+  enabled: boolean;
+  client_id: string;
+  /** Prefer `{ env: "VAR_NAME" }` or `"${env.VAR_NAME}"`. */
+  client_secret: SecretRef;
+  scopes: string[];
+  /** Only for `custom_oidc`. */
+  discovery_url?: string;
+}
+
+export interface OAuthProvidersConfig {
+  google?: OAuthProviderDefinition;
+  github?: OAuthProviderDefinition;
+  okta?: OAuthProviderDefinition;
+  custom_oidc?: OAuthProviderDefinition;
+}
+
+// ── Security ──
+
+export interface PasswordPolicyDefinition {
+  min_length: number;
+  require_uppercase: boolean;
+  require_number: boolean;
+  require_special: boolean;
+}
+
+export interface SessionConfigDefinition {
+  access_token_ttl_secs: number;
+  refresh_token_ttl_secs: number;
+  max_sessions_per_user: number;
+  require_email_verification: boolean;
+}
+
+export interface SecurityConfig {
+  password_policy?: PasswordPolicyDefinition;
+  session?: SessionConfigDefinition;
+}
+
+// ── Branding ──
+
+export interface BrandingConfig {
+  app_name?: string;
+  logo_url?: string;
+  primary_color?: string;
+  secondary_color?: string;
+  welcome_message?: string;
+  welcome_subtitle?: string;
+  /** `"centered"`, `"split-left"`, `"split-right"`, or `"fullscreen"`. */
+  layout?: string;
+  background_image_url?: string;
+  /** 0–100 percentage. */
+  background_focal_point?: { x: number; y: number };
+  background_gradient?: string;
+  /** `"light"`, `"dark"`, or `"auto"`. */
+  color_mode?: string;
+  font_family?: string;
+  terms_url?: string;
+  privacy_url?: string;
+  /** Raw CSS merged into the hosted auth pages. */
+  custom_css?: string;
+}
+
+// ── Top-level shape ──
+
+export interface AuthConfigBlock {
+  resources?: ResourceDefinition[];
+  groups?: GroupDefinition[];
+  relations?: RelationTypeDefinition[];
+  registration?: RegistrationConfig;
+  oauth?: OAuthProvidersConfig;
+  security?: SecurityConfig;
+  branding?: BrandingConfig;
+}
+
+export interface MaravillaConfig {
+  /** All project-level auth settings. Every field is optional — partial adoption is supported. */
+  auth?: AuthConfigBlock;
+}
+
+/**
+ * Identity function that returns the config unchanged — exists purely so the
+ * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense
+ * on every field.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],
+ *   },
+ * });
+ * ```
+ */
+export function defineConfig(config: MaravillaConfig): MaravillaConfig {
+  return config;
+}

package/src/index.ts

@@ -51,6 +51,7 @@ export * from './ren.js';
 export * from './realtime.js';
 export * from './media.js';
 export * from './media-room.js';
+export * from './push.js';
 
 /**
  * Global platform instance injected by Maravilla runtime or development tools.

package/src/push.ts

@@ -0,0 +1,207 @@
+/**
+ * @fileoverview Web Push client SDK for Maravilla tenants.
+ *
+ * Talks to the tenant-origin `/_platform/push` endpoints served by delivery:
+ *   - GET  /vapid-public-key  — fetch the VAPID public key for subscribe
+ *   - POST /subscribe         — create a subscription
+ *   - POST /unsubscribe       — delete a subscription by id (or endpoint)
+ *
+ * The matching service worker is served from `/_platform/push/sw.js` on the
+ * same tenant origin (browsers require same-origin SW registration).
+ */
+
+const DEFAULT_BASE_PATH = '/_platform/push';
+const DEFAULT_SW_PATH = '/_platform/push/sw.js';
+const VISITOR_STORAGE_KEY = 'maravilla.push.visitorId';
+
+export interface RegisterPushOptions {
+  /** Free-form topic strings to tag this subscription with. */
+  topics?: string[];
+  /** Authenticated user id, if any. Takes precedence over visitorId. */
+  userId?: string | null;
+  /** Anonymous visitor id. If omitted and userId is also omitted, one
+   *  is generated and persisted to localStorage under `maravilla.push.visitorId`. */
+  visitorId?: string | null;
+  /** Override the sw.js path (defaults to `/_platform/push/sw.js`). */
+  swPath?: string;
+  /** Override the API base path (defaults to `/_platform/push`). */
+  basePath?: string;
+}
+
+export interface RegisterPushResult {
+  /** The browser PushSubscription (see Web Push spec). */
+  subscription: PushSubscription;
+  /** Server-issued subscription id — pass this back to unregisterPush. */
+  subscriptionId: string;
+}
+
+interface VapidPublicKeyResponse {
+  publicKey: string;
+  contactEmail?: string;
+}
+
+interface ServerSubscription {
+  id: string;
+  [key: string]: unknown;
+}
+
+function assertPushSupported(): void {
+  if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {
+    throw new Error('Web Push is not supported: serviceWorker is unavailable');
+  }
+  if (typeof window === 'undefined' || !('PushManager' in window)) {
+    throw new Error('Web Push is not supported: PushManager is unavailable');
+  }
+}
+
+function base64UrlToArrayBuffer(input: string): ArrayBuffer {
+  const padding = '='.repeat((4 - (input.length % 4)) % 4);
+  const base64 = (input + padding).replace(/-/g, '+').replace(/_/g, '/');
+  const raw = atob(base64);
+  const buffer = new ArrayBuffer(raw.length);
+  const view = new Uint8Array(buffer);
+  for (let i = 0; i < raw.length; i++) {
+    view[i] = raw.charCodeAt(i);
+  }
+  return buffer;
+}
+
+function arrayBufferToBase64Url(buffer: ArrayBuffer | null): string | undefined {
+  if (!buffer) return undefined;
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function randomUuid(): string {
+  const c = typeof crypto !== 'undefined' ? crypto : undefined;
+  if (c && typeof c.randomUUID === 'function') {
+    return c.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (c && typeof c.getRandomValues === 'function') {
+    c.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function resolveVisitorId(
+  userId: string | null | undefined,
+  visitorId: string | null | undefined,
+): string | null {
+  if (visitorId) return visitorId;
+  if (userId) return null;
+  try {
+    const stored = window.localStorage.getItem(VISITOR_STORAGE_KEY);
+    if (stored) return stored;
+    const fresh = randomUuid();
+    window.localStorage.setItem(VISITOR_STORAGE_KEY, fresh);
+    return fresh;
+  } catch {
+    return randomUuid();
+  }
+}
+
+async function fetchVapidPublicKey(basePath: string): Promise<string> {
+  const res = await fetch(`${basePath}/vapid-public-key`, {
+    method: 'GET',
+    credentials: 'same-origin',
+    headers: { Accept: 'application/json' },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch VAPID public key: ${res.status} ${res.statusText}`);
+  }
+  const body = (await res.json()) as VapidPublicKeyResponse;
+  if (!body || typeof body.publicKey !== 'string' || body.publicKey.length === 0) {
+    throw new Error('VAPID public key response is missing `publicKey`');
+  }
+  return body.publicKey;
+}
+
+function extractKeys(sub: PushSubscription): { p256dh?: string; auth?: string } {
+  return {
+    p256dh: arrayBufferToBase64Url(sub.getKey('p256dh')),
+    auth: arrayBufferToBase64Url(sub.getKey('auth')),
+  };
+}
+
+export async function registerPush(
+  opts: RegisterPushOptions = {},
+): Promise<RegisterPushResult> {
+  assertPushSupported();
+
+  const basePath = opts.basePath ?? DEFAULT_BASE_PATH;
+  const swPath = opts.swPath ?? DEFAULT_SW_PATH;
+  const topics = opts.topics ?? [];
+  const userId = opts.userId ?? null;
+  const visitorId = resolveVisitorId(userId, opts.visitorId);
+
+  const publicKey = await fetchVapidPublicKey(basePath);
+  const registration = await navigator.serviceWorker.register(swPath);
+  await navigator.serviceWorker.ready;
+
+  const existing = await registration.pushManager.getSubscription();
+  const subscription =
+    existing ??
+    (await registration.pushManager.subscribe({
+      userVisibleOnly: true,
+      applicationServerKey: base64UrlToArrayBuffer(publicKey),
+    }));
+
+  const { p256dh, auth } = extractKeys(subscription);
+
+  const res = await fetch(`${basePath}/subscribe`, {
+    method: 'POST',
+    credentials: 'same-origin',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({
+      provider: 'web-push',
+      endpoint: subscription.endpoint,
+      p256dh,
+      auth,
+      userId,
+      visitorId,
+      topics,
+    }),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Subscribe failed: ${res.status} ${res.statusText}`);
+  }
+
+  const saved = (await res.json()) as ServerSubscription;
+  if (!saved || typeof saved.id !== 'string' || saved.id.length === 0) {
+    throw new Error('Subscribe response is missing `id`');
+  }
+
+  return { subscription, subscriptionId: saved.id };
+}
+
+export async function unregisterPush(
+  subscriptionId: string,
+  opts: { basePath?: string } = {},
+): Promise<void> {
+  if (!subscriptionId) {
+    throw new Error('subscriptionId is required');
+  }
+  const basePath = opts.basePath ?? DEFAULT_BASE_PATH;
+
+  const res = await fetch(`${basePath}/unsubscribe`, {
+    method: 'POST',
+    credentials: 'same-origin',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ subscriptionId }),
+  });
+
+  if (!res.ok && res.status !== 404) {
+    throw new Error(`Unsubscribe failed: ${res.status} ${res.statusText}`);
+  }
+}

package/tsup.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  entry: ['src/index.ts'],
+  entry: ['src/index.ts', 'src/config.ts', 'src/push.ts'],
   format: ['esm'],
   dts: true,
   splitting: false,