@ima-jin/config 1.0.0

package/dist/index.mjs

@@ -0,0 +1,446 @@
+// src/cors.ts
+import { NextResponse } from "next/server";
+var ORIGIN_PATTERN = /^https:\/\/(dev-)?[a-z-]+\.imajin\.ai$/;
+var LOCAL_PATTERN = /^http:\/\/localhost:\d+$/;
+function isAllowedOrigin(origin) {
+  if (!origin) return false;
+  if (ORIGIN_PATTERN.test(origin)) return true;
+  if (process.env.NODE_ENV !== "production" && LOCAL_PATTERN.test(origin)) return true;
+  return false;
+}
+function corsHeaders(request) {
+  const origin = request.headers.get("origin") || "";
+  const allowed = isAllowedOrigin(origin);
+  return {
+    "Access-Control-Allow-Origin": allowed ? origin : "",
+    "Access-Control-Allow-Credentials": "true",
+    "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Caller-DID",
+    "Vary": "Origin"
+  };
+}
+function corsOptions(request) {
+  return new NextResponse(null, { status: 204, headers: corsHeaders(request) });
+}
+function withCors(response, request) {
+  const headers = corsHeaders(request);
+  Object.entries(headers).forEach(([key, value]) => {
+    response.headers.set(key, value);
+  });
+  return response;
+}
+function validateOrigin(request) {
+  const origin = request.headers.get("origin");
+  if (!origin) return true;
+  return isAllowedOrigin(origin);
+}
+
+// src/services.ts
+var SERVICES = [
+  // Kernel services — individually visible, all run on the kernel process (port 3000/7000)
+  { name: "kernel", label: "Home", icon: "\u{1F3E0}", description: "Network home \u2014 launcher, articles, stats", devPort: 3e3, prodPort: 7e3, schema: null, tier: "core", visibility: "public", category: "kernel" },
+  { name: "auth", label: "Identity", icon: "\u{1F511}", description: "Authentication, keys, and identity management", devPort: 3e3, prodPort: 7e3, schema: "auth", tier: "core", visibility: "authenticated", category: "kernel" },
+  { name: "profile", label: "Profile", icon: "\u{1F464}", description: "Your profile, settings, and display preferences", devPort: 3e3, prodPort: 7e3, schema: "profile", tier: "core", visibility: "authenticated", category: "kernel" },
+  { name: "connections", label: "Connections", icon: "\u{1F91D}", description: "Your network \u2014 people you know and trust", devPort: 3e3, prodPort: 7e3, schema: "connections", tier: "core", visibility: "authenticated", category: "kernel" },
+  { name: "chat", label: "Chat", icon: "\u{1F4AC}", description: "Conversations and group messaging", devPort: 3e3, prodPort: 7e3, schema: "chat", tier: "core", visibility: "authenticated", category: "kernel" },
+  { name: "pay", label: "Wallet", icon: "\u{1F4B0}", description: "Payments, settlements, and MJN balance", devPort: 3e3, prodPort: 7e3, schema: "pay", tier: "core", visibility: "authenticated", category: "kernel" },
+  { name: "media", label: "Media", icon: "\u{1F4C1}", description: "Files, images, and .fair attribution", devPort: 3e3, prodPort: 7e3, schema: "media", tier: "core", visibility: "authenticated", category: "kernel" },
+  { name: "registry", label: "Registry", icon: "\u{1F4E1}", description: "Service registry and DFOS relay", devPort: 3e3, prodPort: 7e3, schema: "registry", tier: "core", visibility: "public", category: "kernel" },
+  { name: "notify", label: "Notify", icon: "\u{1F514}", description: "Notifications and preferences", devPort: 3e3, prodPort: 7e3, schema: "notify", tier: "core", visibility: "internal", category: "kernel" },
+  // Core apps — separate processes
+  { name: "events", label: "Events", icon: "\u{1F3AB}", description: "Event creation, ticketing, and management", devPort: 3006, prodPort: 7006, schema: "events", tier: "core", visibility: "public", category: "core" },
+  // Imajin apps
+  { name: "coffee", label: "Coffee", icon: "\u2615", description: "Tipping and creator support pages", devPort: 3100, prodPort: 7100, schema: "coffee", tier: "imajin", visibility: "creator", category: "creator" },
+  { name: "dykil", label: "Surveys", icon: "\u{1F4CB}", description: "Surveys and do-you-know-if-I-like polls", devPort: 3101, prodPort: 7101, schema: "dykil", tier: "imajin", visibility: "creator", category: "creator" },
+  { name: "links", label: "Links", icon: "\u{1F517}", description: "Link-in-bio pages and click tracking", devPort: 3102, prodPort: 7102, schema: "links", tier: "imajin", visibility: "creator", category: "creator" },
+  { name: "learn", label: "Learn", icon: "\u{1F4DA}", description: "Courses, lessons, and learning progress", devPort: 3103, prodPort: 7103, schema: "learn", tier: "imajin", visibility: "public", category: "core" },
+  { name: "market", label: "Market", icon: "\u{1F3EA}", description: "Local commerce \u2014 buy and sell with trust", devPort: 3104, prodPort: 7104, schema: "market", tier: "imajin", visibility: "public", category: "core" },
+  // Meta — project info and external resources surfaced in the launcher
+  { name: "project", label: "Project", icon: "\u{1F4D6}", description: "Thesis, whitepaper, essays, RFCs", devPort: 3e3, prodPort: 7e3, schema: "public", tier: "core", visibility: "public", category: "meta", wwwPath: "/project" },
+  { name: "github", label: "GitHub", icon: "\u{1F419}", description: "Source code", devPort: 3e3, prodPort: 7e3, schema: "public", tier: "core", visibility: "public", category: "meta", externalUrl: "https://github.com/ima-jin/imajin-ai" },
+  { name: "docs", label: "Docs", icon: "\u{1F4C4}", description: "API documentation", devPort: 3e3, prodPort: 7e3, schema: "public", tier: "core", visibility: "public", category: "meta", wwwPath: "/developer-guide" }
+  // Connected apps (separate repos) will use the plugin architecture (#249).
+  // Not included here — they authenticate via delegated sessions, not the monorepo manifest.
+];
+function getService(name) {
+  return SERVICES.find((s) => s.name === name);
+}
+function getPort(name, env = "dev") {
+  const svc = getService(name);
+  return svc ? env === "prod" ? svc.prodPort : svc.devPort : void 0;
+}
+function getServiceUrl(name, env = "dev") {
+  const port = getPort(name, env);
+  return port ? `http://localhost:${port}` : void 0;
+}
+function getPublicUrl(name, options) {
+  const svc = SERVICES.find((s) => s.name === name);
+  if (svc == null ? void 0 : svc.externalUrl) return svc.externalUrl;
+  const domain = (options == null ? void 0 : options.domain) || "imajin.ai";
+  const prefix = options == null ? void 0 : options.prefix;
+  if (svc == null ? void 0 : svc.wwwPath) {
+    const wwwUrl = getPublicUrl("www", options);
+    return `${wwwUrl}${svc.wwwPath}`;
+  }
+  if (domain.includes("localhost") || (prefix == null ? void 0 : prefix.includes("localhost"))) {
+    const port = getPort(name, "dev");
+    return port ? `http://localhost:${port}` : `http://localhost:3000`;
+  }
+  if (prefix && prefix.includes(".")) {
+    const base = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+    if (name === "www" || name === "kernel") return `https://${base}`;
+    return `https://${base}/${name}`;
+  }
+  const subdomain = prefix ? `${prefix}-${name}` : name;
+  return `https://${subdomain}.${domain}`;
+}
+function buildPublicUrl(name, servicePrefix, domain) {
+  if (!servicePrefix && !domain && typeof process !== "undefined") {
+    const envKey = `NEXT_PUBLIC_${name.toUpperCase()}_URL`;
+    const explicit = process.env[envKey];
+    if (explicit) return explicit;
+  }
+  const p = servicePrefix ?? (typeof process !== "undefined" ? process.env.NEXT_PUBLIC_SERVICE_PREFIX : void 0) ?? "https://";
+  const d = domain ?? (typeof process !== "undefined" ? process.env.NEXT_PUBLIC_DOMAIN : void 0) ?? "imajin.ai";
+  if (p.includes("localhost") || d.includes("localhost")) {
+    const port = getPort(name, "dev");
+    return port ? `http://localhost:${port}` : `http://localhost:3000`;
+  }
+  if (!servicePrefix && !domain) {
+    return name === "kernel" ? "" : `/${name}`;
+  }
+  const match = p.replace(/^https?:\/\//, "").replace(/-$/, "") || void 0;
+  return getPublicUrl(name, { prefix: match, domain: d });
+}
+var SERVICE_NAMES = SERVICES.map((s) => s.name);
+function servicesByTier(tier) {
+  return SERVICES.filter((s) => s.tier === tier);
+}
+function servicesByVisibility(visibility) {
+  return SERVICES.filter((s) => s.visibility === visibility);
+}
+function buildServiceUrlMap(env, mode = "dev") {
+  const map = {};
+  for (const svc of SERVICES) {
+    const envKey = `${svc.name.toUpperCase()}_SERVICE_URL`;
+    const port = mode === "prod" ? svc.prodPort : svc.devPort;
+    map[svc.name] = env[envKey] || `http://localhost:${port}`;
+  }
+  return map;
+}
+
+// src/session.ts
+function getSessionCookieName(env) {
+  const resolved = env ?? (typeof process !== "undefined" && (process.env.IMAJIN_ENV === "dev" || process.env.NODE_ENV === "development") ? "dev" : "prod");
+  return resolved === "dev" ? "imajin_session_dev" : "imajin_session";
+}
+var SESSION_COOKIE_NAME = getSessionCookieName();
+function isLocalhost() {
+  if (typeof process === "undefined") return false;
+  const prefix = process.env.NEXT_PUBLIC_SERVICE_PREFIX ?? "";
+  return prefix.includes("localhost");
+}
+function getSessionCookieOptions(env) {
+  const local = isLocalhost();
+  return {
+    name: getSessionCookieName(env),
+    options: {
+      httpOnly: true,
+      secure: !local,
+      sameSite: local ? "lax" : "none",
+      path: "/",
+      ...local ? {} : { domain: ".imajin.ai" },
+      maxAge: 60 * 60 * 24
+      // 24 hours
+    }
+  };
+}
+
+// src/base-path.ts
+function getBasePath() {
+  return process.env.NEXT_PUBLIC_BASE_PATH || "";
+}
+function apiUrl(path) {
+  const base = getBasePath();
+  if (!base) return path;
+  if (path.startsWith(base)) return path;
+  return `${base}${path}`;
+}
+function apiFetch(path, init) {
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return fetch(path, init);
+  }
+  return fetch(apiUrl(path), init);
+}
+
+// src/handles.ts
+var HANDLE_PATTERN = /^[a-z0-9._-]{3,30}$/;
+var HANDLE_EDGE = /^[.\-]|[.\-]$/;
+var HANDLE_CONSECUTIVE = /[.\-]{2}/;
+var HANDLE_INPUT_PATTERN = "[a-z0-9._\\-]{3,30}";
+var HANDLE_ALLOWED_CHARS = /[^a-z0-9._-]/g;
+var RESERVED_HANDLES = /* @__PURE__ */ new Set([
+  "admin",
+  "api",
+  "app",
+  "auth",
+  "blog",
+  "coffee",
+  "connect",
+  "dashboard",
+  "docs",
+  "edit",
+  "events",
+  "help",
+  "home",
+  "imajin",
+  "inbox",
+  "links",
+  "login",
+  "logout",
+  "mail",
+  "news",
+  "pay",
+  "profile",
+  "register",
+  "search",
+  "settings",
+  "signup",
+  "status",
+  "support",
+  "team",
+  "www"
+]);
+function isValidHandle(handle) {
+  if (!HANDLE_PATTERN.test(handle)) return false;
+  if (HANDLE_EDGE.test(handle)) return false;
+  if (HANDLE_CONSECUTIVE.test(handle)) return false;
+  return true;
+}
+function isReservedHandle(handle) {
+  return RESERVED_HANDLES.has(handle);
+}
+function normalizeHandleInput(value) {
+  return value.toLowerCase().replace(HANDLE_ALLOWED_CHARS, "");
+}
+var HANDLE_ERROR = "Handle must be 3-30 characters: lowercase letters, numbers, dots, hyphens, underscores";
+
+// src/routes.ts
+var eventPath = (eventId) => `/e/${eventId}`;
+var eventEditPath = (eventId) => `/e/${eventId}/edit`;
+var eventRegisterPath = (eventId, ticketId) => `/e/${eventId}/register/${ticketId}`;
+var eventMyTicketsPath = (eventId) => `/e/${eventId}/my-tickets`;
+var eventCheckoutSuccessPath = (eventId) => `/e/${eventId}#tickets`;
+var eventAdminPath = (eventId) => `/admin/${eventId}`;
+var eventsDashboardPath = () => `/dashboard`;
+var eventsCreatePath = () => `/create`;
+var eventsCheckoutSuccessPath = () => `/checkout/success`;
+var eventsAdminListPath = () => `/admin`;
+var eventUrl = (baseUrl, eventId) => `${baseUrl}/e/${eventId}`;
+var eventEditUrl = (baseUrl, eventId) => `${baseUrl}/e/${eventId}/edit`;
+var eventRegisterUrl = (baseUrl, eventId, ticketId) => `${baseUrl}/e/${eventId}/register/${ticketId}`;
+var eventMyTicketsUrl = (baseUrl, eventId) => `${baseUrl}/e/${eventId}/my-tickets`;
+var profilePath = (handle) => `/p/${handle}`;
+var profileEditPath = () => `/p/edit`;
+var profileLoginPath = () => `/profile/login`;
+var profileRegisterPath = () => `/profile/register`;
+var profileUrl = (baseUrl, handle) => `${baseUrl}/p/${handle}`;
+var authLoginPath = () => `/auth/login`;
+var authRegisterPath = () => `/auth/register`;
+var authOnboardPath = () => `/auth/onboard`;
+var authSettingsPath = () => `/auth/settings`;
+var authSecurityPath = () => `/auth/settings/security`;
+var authGroupSettingsPath = (groupDid) => `/auth/groups/${groupDid}/settings`;
+var authGroupsPath = () => `/auth/groups`;
+var authNewGroupPath = () => `/auth/groups/new`;
+var authAgentsPath = () => `/auth/agents`;
+var authAppsPath = () => `/auth/apps`;
+var authAttestationsPath = () => `/auth/attestations`;
+var authAuthorizePath = () => `/auth/authorize`;
+var authDeveloperAppsPath = () => `/auth/developer/apps`;
+var authDeveloperAppPath = (appId) => `/auth/developer/apps/${appId}`;
+var authMembersPath = () => `/auth/members`;
+var authNotificationsPath = () => `/auth/notifications`;
+var authStubsPath = (did) => `/auth/stubs/${did}`;
+var authNewStubPath = () => `/auth/stubs/new`;
+var chatConversationsPath = () => `/chat/conversations`;
+var chatConversationPath = (type, slug) => `/chat/conversations/${type}/${slug}`;
+var chatPath = () => `/chat`;
+var connectionsPath = () => `/connections`;
+var connectionsInvitePath = (did, code) => `/connections/invite/${did}/${code}`;
+var connectionsPodPath = (id) => `/connections/pods/${id}`;
+var payPath = () => `/pay`;
+var payHistoryPath = () => `/pay/history`;
+var payPayoutsPath = () => `/pay/payouts`;
+var payTopupPath = () => `/pay/topup`;
+var payTopupSuccessPath = () => `/pay/topup/success`;
+var mediaPath = () => `/media`;
+var learnCoursePath = (slug) => `/course/${slug}`;
+var learnCourseLessonPath = (slug, lessonId) => `/course/${slug}/${lessonId}`;
+var learnCoursePresentPath = (slug) => `/course/${slug}/present`;
+var learnDashboardPath = () => `/dashboard`;
+var learnCourseDashboardPath = (slug) => `/dashboard/${slug}`;
+var learnCourseStudentsPath = (slug) => `/dashboard/${slug}/students`;
+var learnHandlePath = (handle) => `/${handle}`;
+var coffeeHandlePath = (handle) => `/${handle}`;
+var coffeeDashboardPath = () => `/dashboard`;
+var coffeeEditPath = () => `/edit`;
+var coffeeSuccessPath = () => `/success`;
+var dykilHandlePath = (handle) => `/${handle}`;
+var dykilSurveyPath = (handle, surveyId) => `/${handle}/${surveyId}`;
+var dykilCreatePath = () => `/create`;
+var dykilDashboardPath = () => `/dashboard`;
+var dykilResultsPath = (id) => `/survey/${id}/results`;
+var dykilEmbedPath = (surveyId) => `/embed/${surveyId}`;
+var linksHandlePath = (handle) => `/${handle}`;
+var linksDashboardPath = () => `/dashboard`;
+var linksEditPath = () => `/edit`;
+var marketListingPath = (id) => `/listings/${id}`;
+var marketListingEditPath = (id) => `/listings/${id}/edit`;
+var marketNewListingPath = () => `/listings/new`;
+var marketSellerPath = (handle) => `/seller/${handle}`;
+var marketCheckoutSuccessPath = () => `/checkout/success`;
+var marketDashboardPath = () => `/dashboard`;
+var marketSettingsPath = () => `/settings`;
+var articlesPath = () => `/articles`;
+var articleAuthorPath = (handle) => `/articles/${handle}`;
+var articlePath = (handle, slug) => `/articles/${handle}/${slug}`;
+var registryPath = () => `/registry`;
+var registryDocsPath = () => `/registry/docs`;
+var buildPath = () => `/build`;
+var bumpPath = () => `/bump`;
+var bugsPath = () => `/bugs`;
+var bugsAdminPath = () => `/bugs/admin`;
+var healthPath = () => `/health`;
+var privacyPath = () => `/privacy`;
+var whitepaperPath = () => `/whitepaper`;
+var subscribePath = () => `/subscribe`;
+var developerGuidePath = () => `/developer-guide`;
+var docsPath = () => `/docs`;
+var projectPath = () => `/project`;
+var notifyPath = () => `/notify`;
+var notifySettingsPath = () => `/notify/settings`;
+export {
+  HANDLE_ALLOWED_CHARS,
+  HANDLE_ERROR,
+  HANDLE_INPUT_PATTERN,
+  HANDLE_PATTERN,
+  RESERVED_HANDLES,
+  SERVICES,
+  SERVICE_NAMES,
+  SESSION_COOKIE_NAME,
+  apiFetch,
+  apiUrl,
+  articleAuthorPath,
+  articlePath,
+  articlesPath,
+  authAgentsPath,
+  authAppsPath,
+  authAttestationsPath,
+  authAuthorizePath,
+  authDeveloperAppPath,
+  authDeveloperAppsPath,
+  authGroupSettingsPath,
+  authGroupsPath,
+  authLoginPath,
+  authMembersPath,
+  authNewGroupPath,
+  authNewStubPath,
+  authNotificationsPath,
+  authOnboardPath,
+  authRegisterPath,
+  authSecurityPath,
+  authSettingsPath,
+  authStubsPath,
+  bugsAdminPath,
+  bugsPath,
+  buildPath,
+  buildPublicUrl,
+  buildServiceUrlMap,
+  bumpPath,
+  chatConversationPath,
+  chatConversationsPath,
+  chatPath,
+  coffeeDashboardPath,
+  coffeeEditPath,
+  coffeeHandlePath,
+  coffeeSuccessPath,
+  connectionsInvitePath,
+  connectionsPath,
+  connectionsPodPath,
+  corsHeaders,
+  corsOptions,
+  developerGuidePath,
+  docsPath,
+  dykilCreatePath,
+  dykilDashboardPath,
+  dykilEmbedPath,
+  dykilHandlePath,
+  dykilResultsPath,
+  dykilSurveyPath,
+  eventAdminPath,
+  eventCheckoutSuccessPath,
+  eventEditPath,
+  eventEditUrl,
+  eventMyTicketsPath,
+  eventMyTicketsUrl,
+  eventPath,
+  eventRegisterPath,
+  eventRegisterUrl,
+  eventUrl,
+  eventsAdminListPath,
+  eventsCheckoutSuccessPath,
+  eventsCreatePath,
+  eventsDashboardPath,
+  getPort,
+  getPublicUrl,
+  getService,
+  getServiceUrl,
+  getSessionCookieName,
+  getSessionCookieOptions,
+  healthPath,
+  isAllowedOrigin,
+  isReservedHandle,
+  isValidHandle,
+  learnCourseDashboardPath,
+  learnCourseLessonPath,
+  learnCoursePath,
+  learnCoursePresentPath,
+  learnCourseStudentsPath,
+  learnDashboardPath,
+  learnHandlePath,
+  linksDashboardPath,
+  linksEditPath,
+  linksHandlePath,
+  marketCheckoutSuccessPath,
+  marketDashboardPath,
+  marketListingEditPath,
+  marketListingPath,
+  marketNewListingPath,
+  marketSellerPath,
+  marketSettingsPath,
+  mediaPath,
+  normalizeHandleInput,
+  notifyPath,
+  notifySettingsPath,
+  payHistoryPath,
+  payPath,
+  payPayoutsPath,
+  payTopupPath,
+  payTopupSuccessPath,
+  privacyPath,
+  profileEditPath,
+  profileLoginPath,
+  profilePath,
+  profileRegisterPath,
+  profileUrl,
+  projectPath,
+  registryDocsPath,
+  registryPath,
+  servicesByTier,
+  servicesByVisibility,
+  subscribePath,
+  validateOrigin,
+  whitepaperPath,
+  withCors
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@ima-jin/config",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "dependencies": {
+    "@ima-jin/tokens": "^1.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/base-path.ts

@@ -0,0 +1,73 @@
+/**
+ * basePath-aware utilities for userspace apps running behind Next.js basePath.
+ *
+ * Next.js `basePath` auto-prefixes <Link> and router.push() but NOT:
+ *   - fetch() calls
+ *   - <a href=""> tags
+ *   - window.location assignments
+ *
+ * These utilities read NEXT_PUBLIC_BASE_PATH (set automatically by Next.js
+ * when basePath is configured) and prepend it where needed.
+ *
+ * Usage:
+ *   import { apiFetch, apiUrl } from '@imajin/config';
+ *
+ *   // Instead of: fetch('/api/listings')
+ *   apiFetch('/api/listings')
+ *
+ *   // For <a> tags or window.location:
+ *   <a href={apiUrl('/dashboard')}>Dashboard</a>
+ *   window.location.href = apiUrl('/dashboard');
+ */
+
+/**
+ * Get the basePath prefix. Works in both browser and server contexts.
+ * Returns empty string when no basePath is configured (standalone mode).
+ */
+function getBasePath(): string {
+  return process.env.NEXT_PUBLIC_BASE_PATH || '';
+}
+
+/**
+ * Prepend basePath to any root-relative path.
+ *
+ *   apiUrl('/api/listings')  → '/market/api/listings'  (with basePath: '/market')
+ *   apiUrl('/dashboard')     → '/market/dashboard'
+ *   apiUrl('/api/listings')  → '/api/listings'          (standalone, no basePath)
+ */
+export function apiUrl(path: string): string {
+  const base = getBasePath();
+  if (!base) return path;
+  // Avoid double-prefixing
+  if (path.startsWith(base)) return path;
+  return `${base}${path}`;
+}
+
+/**
+ * basePath-aware fetch wrapper. Drop-in replacement for fetch() with
+ * root-relative paths.
+ *
+ *   apiFetch('/api/listings')           → fetch('/market/api/listings')
+ *   apiFetch('/api/listings', { ... })  → fetch('/market/api/listings', { ... })
+ *
+ * Absolute URLs (http://, https://) are passed through unchanged.
+ *
+ * TODO(WO2/correlation): For server-side service-to-service calls, callers should
+ * forward the X-Correlation-Id header so the full request chain shares one ID.
+ * apiFetch is browser-side too, so we can't read headers here automatically —
+ * instead, pass it explicitly via init.headers when calling from a withLogger handler:
+ *
+ *   apiFetch('/api/something', {
+ *     headers: { 'x-correlation-id': correlationId },
+ *   });
+ *
+ * When WO3 instruments services, each withLogger handler receives correlationId in
+ * ctx and should forward it on any outbound apiFetch/fetch calls.
+ */
+export function apiFetch(path: string, init?: RequestInit): Promise<Response> {
+  // Don't prefix absolute URLs
+  if (path.startsWith('http://') || path.startsWith('https://')) {
+    return fetch(path, init);
+  }
+  return fetch(apiUrl(path), init);
+}

package/src/cors.ts

@@ -0,0 +1,43 @@
+import { NextRequest, NextResponse } from "next/server";
+
+// Match *.imajin.ai, dev-*.imajin.ai, and localhost for dev
+const ORIGIN_PATTERN = /^https:\/\/(dev-)?[a-z-]+\.imajin\.ai$/;
+const LOCAL_PATTERN = /^http:\/\/localhost:\d+$/;
+
+export function isAllowedOrigin(origin: string | null): boolean {
+  if (!origin) return false;
+  if (ORIGIN_PATTERN.test(origin)) return true;
+  if (process.env.NODE_ENV !== "production" && LOCAL_PATTERN.test(origin)) return true;
+  return false;
+}
+
+export function corsHeaders(request: NextRequest): Record<string, string> {
+  const origin = request.headers.get("origin") || "";
+  const allowed = isAllowedOrigin(origin);
+  return {
+    "Access-Control-Allow-Origin": allowed ? origin : "",
+    "Access-Control-Allow-Credentials": "true",
+    "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Caller-DID",
+    "Vary": "Origin",
+  };
+}
+
+export function corsOptions(request: NextRequest): NextResponse {
+  return new NextResponse(null, { status: 204, headers: corsHeaders(request) });
+}
+
+export function withCors(response: NextResponse, request: NextRequest): NextResponse {
+  const headers = corsHeaders(request);
+  Object.entries(headers).forEach(([key, value]) => {
+    response.headers.set(key, value);
+  });
+  return response;
+}
+
+export function validateOrigin(request: NextRequest): boolean {
+  const origin = request.headers.get("origin");
+  // Allow server-side calls (no origin header)
+  if (!origin) return true;
+  return isAllowedOrigin(origin);
+}

package/src/handles.ts

@@ -0,0 +1,51 @@
+/**
+ * Handle validation and normalization.
+ *
+ * Handles are node-scoped today, globally unique via DFOS chain in the future.
+ * Pattern: lowercase alphanumeric + dots, hyphens, underscores. 3-30 chars.
+ * No leading/trailing dots or hyphens. No consecutive dots or hyphens.
+ */
+
+/** Regex: the full allowed character set, length enforced */
+export const HANDLE_PATTERN = /^[a-z0-9._-]{3,30}$/;
+
+/** Regex: disallowed leading/trailing characters */
+const HANDLE_EDGE = /^[.\-]|[.\-]$/;
+
+/** Regex: consecutive dots or hyphens */
+const HANDLE_CONSECUTIVE = /[.\-]{2}/;
+
+/** HTML input pattern attribute (no anchors, no flags) */
+export const HANDLE_INPUT_PATTERN = '[a-z0-9._\\-]{3,30}';
+
+/** Characters allowed in handles — use in onChange filters */
+export const HANDLE_ALLOWED_CHARS = /[^a-z0-9._-]/g;
+
+/** Reserved handles that cannot be claimed */
+export const RESERVED_HANDLES = new Set([
+  'admin', 'api', 'app', 'auth', 'blog', 'coffee', 'connect', 'dashboard',
+  'docs', 'edit', 'events', 'help', 'home', 'imajin', 'inbox', 'links', 'login',
+  'logout', 'mail', 'news', 'pay', 'profile', 'register', 'search', 'settings',
+  'signup', 'status', 'support', 'team', 'www',
+]);
+
+/** Validate handle format (does NOT check reserved or uniqueness) */
+export function isValidHandle(handle: string): boolean {
+  if (!HANDLE_PATTERN.test(handle)) return false;
+  if (HANDLE_EDGE.test(handle)) return false;
+  if (HANDLE_CONSECUTIVE.test(handle)) return false;
+  return true;
+}
+
+/** Check if handle is reserved */
+export function isReservedHandle(handle: string): boolean {
+  return RESERVED_HANDLES.has(handle);
+}
+
+/** Normalize input: lowercase, strip disallowed chars */
+export function normalizeHandleInput(value: string): string {
+  return value.toLowerCase().replace(HANDLE_ALLOWED_CHARS, '');
+}
+
+/** Validation error message */
+export const HANDLE_ERROR = 'Handle must be 3-30 characters: lowercase letters, numbers, dots, hyphens, underscores';