@stringpush/sdk 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @stringpush/sdk
+
+Framework-agnostic plain JavaScript SDK for the Translation Platform.
+
+## Install
+
+```bash
+pnpm add @stringpush/sdk
+```
+
+## Usage
+
+```ts
+import { init, setLocale, t } from "@stringpush/sdk";
+
+await init({
+  applicationId: "your-application-id",
+  environment: "staging",
+  locale: "en",
+  apiKey: "trt_…",
+  apiBaseUrl: "http://localhost:3000",
+  origin: "http://localhost:5173",
+  onLocaleChange: () => app.rerender(),
+  onTranslationsUpdated: () => app.rerender(),
+});
+
+console.log(t("common.greeting"));
+console.log(t("common.welcome", { name: "Ada" }));
+console.log(t("items.count", { count: 3 }));
+
+await setLocale("fr");
+```
+
+`init` fetches the manifest and active locale bundle using the runtime API key. Bundle URLs from the manifest are resolved against `apiBaseUrl`.
+
+### MAU reporting (optional)
+
+```ts
+await init({
+  // …same as above
+  reportUsage: true, // POST /v1/usage/mau after init (SHA-256 of anonymous localStorage id)
+});
+```
+
+Enable when your plan includes MAU metering. No PII is sent — only a stable hash per browser per calendar month.
+
+`t(key, values)` supports ICU MessageFormat (plural, select) and `{name}` interpolation via `intl-messageformat`. Configure missing-key behavior with `missingKeyFallback` (`key`, `default_message`, or `empty`) and optional `defaultMessages` at init.
+
+See [examples/vanilla](../../examples/vanilla/) for a runnable demo.
+
+### Staging vs production
+
+Pass `environment: "staging"` or `environment: "production"` in `init()`. The manifest and bundle URLs are scoped per environment (`/bundles/{projectId}/staging/…` vs `…/production/…`). Use **staging** for pre-release copy and overlay edit mode; use **production** for live customer traffic after promote + publish in admin.
+
+Overlay edit mode is intended for **staging** only unless your organization explicitly enables production overlay (see platform `docs/CONTEXT.md` D-014).
+
+## Edit mode (staging overlay)
+
+### Recommended: edit launcher (M2-SDK-05)
+
+Arm with `?translation_edit=1` only — a **Translate** FAB appears (staging). Users sign in, then overlay starts on click. JWT is stored in `sessionStorage`, not left in the query string.
+
+```ts
+await init({
+  /* … */
+  environment: "staging",
+  editLauncher: {
+    signInUrl: "https://admin.example.com/overlay-grant", // redirect auth
+    // or requestEditToken: async () => { … } // demo/local only
+  },
+});
+```
+
+Optional shared secret: `?translation_edit=1&translation_edit_key=<armingKey>` when `editLauncher.armingKey` is set.
+
+After SSO, redirect back with `#edit_token=<jwt>`; the SDK persists it and strips the hash from the URL.
+
+### Magic link (auto-enable)
+
+`?translation_edit=1&edit_token=<jwt>` still auto-enables overlay on load (QA links).
+
+### Programmatic
+
+```ts
+await init({ /* … */ editToken: "<jwt>" });
+await enableEditMode();
+disableEditMode();
+```
+
+The overlay UI, launcher, and WebSocket client load in **separate chunks** (not in the default `import` bundle).
+
+### Key resolution (edit mode)
+
+Mark translatable nodes with `data-i18n-key="your.key"` or register a DOM resolver:
+
+```ts
+import { registerResolver } from "@stringpush/sdk";
+
+registerResolver((element) => (element.id === "title" ? "home.title" : null));
+```
+
+Or mark nodes with `data-i18n-key="your.key"` (see exported constant `I18N_KEY_ATTR`).
+
+In edit mode, hovering or focusing a resolved element shows a highlight and the key path. **Click** a highlighted element to open the side panel and edit values for all project locales (saved via `PATCH /v1/overlay/values` with the edit JWT). After a successful save, the in-memory catalog for the active locale updates and `onTranslationsUpdated` runs.
+
+If another editor changed the same value, the panel shows a **409 conflict** banner with a reload option.
+
+While edit mode is active, the overlay WebSocket applies `translation.updated` (same environment, with version guards) to the in-memory catalog, refreshes an open edit panel for the same key, and refetches the manifest when a newer `bundle.published` arrives for the active locale — all invoke `onTranslationsUpdated`. The client reconnects automatically if the socket drops.
+
+## Security notes
+
+- **Runtime key** (`trt_…`): read-only; safe in customer frontends; restrict via application **allowed domains**.
+- **Edit token**: short-lived; overlay/write only; never commit or ship in production bundles.
+- **Environment**: use `staging` for overlay QA; production edit requires the organization to enable **production overlay** in admin Settings (Business+), or the API env `EDIT_ON_PRODUCTION_ALLOWED=true` for local ops.
+- **Origin**: set `origin` in `init()` to match an allowlisted domain (defaults to `window.location.origin`).
+
+## Troubleshooting
+
+| Symptom | What to check |
+|---------|----------------|
+| Manifest `401` / `403` | Runtime API key; `Origin` header vs allowlisted domains |
+| Overlay `403` | Page `Origin` not in application allowlist |
+| `edit token required` | Pass `editToken`, or `?translation_edit=1&edit_token=` |
+| `edit token is malformed` | JWT truncated in URL — use `encodeURIComponent` |
+| `environment does not match` | `init({ environment })` must match the edit session environment |
+| `401` on overlay save | Edit JWT expired — re-issue via `POST /v1/auth/edit-session` |
+| `409` on save | Another editor saved first — use Reload in the panel |
+| Live updates missing | Realtime gateway + `REDIS_URL`; same project/environment |
+| CORS errors on manifest or overlay | API must allow your origin; add hostname to application **allowed domains** |
+| CORS errors on bundle CDN | Hosted CDN allows `*`; SDK omits runtime key on cross-origin bundle URLs. BYO CDN: set `Access-Control-Allow-Origin: *` (or your origins) on bundle GET |
+
+Full staging setup: [docs/integration/overlay-staging.md](../../docs/integration/overlay-staging.md).
+
+See [docs/big-picture.md](../../docs/big-picture.md) for the full integration model.

package/dist/chunk-FROJCNV7.umd.cjs

@@ -0,0 +1,153 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/edit-token.ts
+var EDIT_TOKEN_QUERY_PARAM = "edit_token";
+var EDIT_MODE_QUERY_PARAM = "translation_edit";
+var EDIT_LAUNCHER_KEY_QUERY_PARAM = "translation_edit_key";
+var EDIT_TOKEN_STORAGE_KEY = "@translation/edit-token";
+function isEditModeQueryEnabled() {
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return false;
+  }
+  const params = new URLSearchParams(
+    globalThis.location.search
+  );
+  const value = params.get(EDIT_MODE_QUERY_PARAM);
+  return value === "1" || value === "true";
+}
+function readEditTokenFromQuery() {
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return null;
+  }
+  const params = new URLSearchParams(
+    globalThis.location.search
+  );
+  return params.get(EDIT_TOKEN_QUERY_PARAM);
+}
+function readEditTokenFromHash() {
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return null;
+  }
+  const hash = globalThis.location.hash;
+  if (!hash || hash.length <= 1) {
+    return null;
+  }
+  const params = new URLSearchParams(hash.startsWith("#") ? hash.slice(1) : hash);
+  return params.get(EDIT_TOKEN_QUERY_PARAM);
+}
+function isEditLauncherArmed(launcher) {
+  if (!isEditModeQueryEnabled()) {
+    return false;
+  }
+  if (!_optionalChain([launcher, 'optionalAccess', _ => _.armingKey])) {
+    return true;
+  }
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return false;
+  }
+  const params = new URLSearchParams(
+    globalThis.location.search
+  );
+  return params.get(EDIT_LAUNCHER_KEY_QUERY_PARAM) === launcher.armingKey;
+}
+function readEditTokenFromStorage() {
+  if (typeof globalThis === "undefined" || !("sessionStorage" in globalThis)) {
+    return null;
+  }
+  try {
+    return _nullishCoalesce(globalThis.sessionStorage.getItem(
+      EDIT_TOKEN_STORAGE_KEY
+    ), () => ( null));
+  } catch (e) {
+    return null;
+  }
+}
+function persistEditToken(token) {
+  if (typeof globalThis === "undefined" || !("sessionStorage" in globalThis)) {
+    return;
+  }
+  try {
+    globalThis.sessionStorage.setItem(
+      EDIT_TOKEN_STORAGE_KEY,
+      token
+    );
+  } catch (e2) {
+  }
+}
+function resolveEditToken(options, override) {
+  const token = _nullishCoalesce(_nullishCoalesce(_nullishCoalesce(_nullishCoalesce(override, () => ( options.editToken)), () => ( readEditTokenFromQuery())), () => ( readEditTokenFromHash())), () => ( readEditTokenFromStorage()));
+  if (token) {
+    persistEditToken(token);
+  }
+  return token;
+}
+function stripEditTokenFromUrl() {
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return;
+  }
+  const win = globalThis;
+  const url = new URL(win.location.href);
+  url.searchParams.delete(EDIT_TOKEN_QUERY_PARAM);
+  if (url.hash) {
+    const hashParams = new URLSearchParams(url.hash.slice(1));
+    if (hashParams.has(EDIT_TOKEN_QUERY_PARAM)) {
+      hashParams.delete(EDIT_TOKEN_QUERY_PARAM);
+      const nextHash = hashParams.toString();
+      url.hash = nextHash ? `#${nextHash}` : "";
+    }
+  }
+  const next = `${url.pathname}${url.search}${url.hash}`;
+  win.history.replaceState(win.history.state, "", next);
+}
+function shouldAutoEnableEditMode(options) {
+  if (options.autoEnableEditFromQuery === false) {
+    return false;
+  }
+  return isEditModeQueryEnabled() && resolveEditToken(options) !== null;
+}
+
+// src/edit-token-decode.ts
+function decodeEditTokenClaims(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) {
+    return null;
+  }
+  try {
+    const payloadJson = base64UrlDecode(parts[1]);
+    const payload = JSON.parse(payloadJson);
+    const project = payload.project;
+    const app = payload.app;
+    const env = payload.env;
+    const envName = payload.envName;
+    if (typeof project !== "string" || typeof app !== "string" || typeof env !== "string" || typeof envName !== "string") {
+      return null;
+    }
+    return {
+      projectId: project,
+      applicationId: app,
+      environmentId: env,
+      environmentName: envName
+    };
+  } catch (e3) {
+    return null;
+  }
+}
+function base64UrlDecode(segment) {
+  const padded = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = padded.length % 4 === 0 ? "" : "=".repeat(4 - padded.length % 4);
+  if (typeof atob === "function") {
+    return atob(padded + pad);
+  }
+  return Buffer.from(padded + pad, "base64").toString("utf8");
+}
+
+
+
+
+
+
+
+
+
+
+
+exports.readEditTokenFromQuery = readEditTokenFromQuery; exports.readEditTokenFromHash = readEditTokenFromHash; exports.isEditLauncherArmed = isEditLauncherArmed; exports.readEditTokenFromStorage = readEditTokenFromStorage; exports.persistEditToken = persistEditToken; exports.resolveEditToken = resolveEditToken; exports.stripEditTokenFromUrl = stripEditTokenFromUrl; exports.shouldAutoEnableEditMode = shouldAutoEnableEditMode; exports.decodeEditTokenClaims = decodeEditTokenClaims;
+//# sourceMappingURL=chunk-FROJCNV7.umd.cjs.map

package/dist/chunk-FROJCNV7.umd.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/mitopalov/work/translations/packages/sdk/dist/chunk-FROJCNV7.umd.cjs","../src/edit-token.ts","../src/edit-token-decode.ts"],"names":[],"mappings":"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","file":"/home/mitopalov/work/translations/packages/sdk/dist/chunk-FROJCNV7.umd.cjs","sourcesContent":[null,"/**\n * Resolves overlay edit JWT from init options, URL, or sessionStorage (M2-SDK-01).\n */\nimport type { InitOptions } from \"./types.js\";\n\nexport const EDIT_TOKEN_QUERY_PARAM = \"edit_token\";\nexport const EDIT_MODE_QUERY_PARAM = \"translation_edit\";\nexport const EDIT_LAUNCHER_KEY_QUERY_PARAM = \"translation_edit_key\";\nexport const EDIT_TOKEN_STORAGE_KEY = \"@translation/edit-token\";\n\nexport function isEditModeQueryEnabled(): boolean {\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return false;\n  }\n  const params = new URLSearchParams(\n    (globalThis as Window & typeof globalThis).location.search,\n  );\n  const value = params.get(EDIT_MODE_QUERY_PARAM);\n  return value === \"1\" || value === \"true\";\n}\n\nexport function readEditTokenFromQuery(): string | null {\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return null;\n  }\n  const params = new URLSearchParams(\n    (globalThis as Window & typeof globalThis).location.search,\n  );\n  return params.get(EDIT_TOKEN_QUERY_PARAM);\n}\n\nexport function readEditTokenFromHash(): string | null {\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return null;\n  }\n  const hash = (globalThis as Window & typeof globalThis).location.hash;\n  if (!hash || hash.length <= 1) {\n    return null;\n  }\n  const params = new URLSearchParams(hash.startsWith(\"#\") ? hash.slice(1) : hash);\n  return params.get(EDIT_TOKEN_QUERY_PARAM);\n}\n\nexport function isEditLauncherArmed(launcher?: { armingKey?: string }): boolean {\n  if (!isEditModeQueryEnabled()) {\n    return false;\n  }\n  if (!launcher?.armingKey) {\n    return true;\n  }\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return false;\n  }\n  const params = new URLSearchParams(\n    (globalThis as Window & typeof globalThis).location.search,\n  );\n  return params.get(EDIT_LAUNCHER_KEY_QUERY_PARAM) === launcher.armingKey;\n}\n\nexport function readEditTokenFromStorage(): string | null {\n  if (typeof globalThis === \"undefined\" || !(\"sessionStorage\" in globalThis)) {\n    return null;\n  }\n  try {\n    return (\n      (globalThis as Window & typeof globalThis).sessionStorage.getItem(\n        EDIT_TOKEN_STORAGE_KEY,\n      ) ?? null\n    );\n  } catch {\n    return null;\n  }\n}\n\nexport function persistEditToken(token: string): void {\n  if (typeof globalThis === \"undefined\" || !(\"sessionStorage\" in globalThis)) {\n    return;\n  }\n  try {\n    (globalThis as Window & typeof globalThis).sessionStorage.setItem(\n      EDIT_TOKEN_STORAGE_KEY,\n      token,\n    );\n  } catch {\n    // Intent: private mode or blocked storage — overlay still works for this page load.\n  }\n}\n\nexport function resolveEditToken(\n  options: InitOptions,\n  override?: string,\n): string | null {\n  const token =\n    override ??\n    options.editToken ??\n    readEditTokenFromQuery() ??\n    readEditTokenFromHash() ??\n    readEditTokenFromStorage();\n  if (token) {\n    persistEditToken(token);\n  }\n  return token;\n}\n\n/**\n * Removes edit JWT from the URL after persisting to sessionStorage (M2-SDK-05).\n */\nexport function stripEditTokenFromUrl(): void {\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return;\n  }\n  const win = globalThis as Window & typeof globalThis;\n  const url = new URL(win.location.href);\n  url.searchParams.delete(EDIT_TOKEN_QUERY_PARAM);\n  if (url.hash) {\n    const hashParams = new URLSearchParams(url.hash.slice(1));\n    if (hashParams.has(EDIT_TOKEN_QUERY_PARAM)) {\n      hashParams.delete(EDIT_TOKEN_QUERY_PARAM);\n      const nextHash = hashParams.toString();\n      url.hash = nextHash ? `#${nextHash}` : \"\";\n    }\n  }\n  const next = `${url.pathname}${url.search}${url.hash}`;\n  win.history.replaceState(win.history.state, \"\", next);\n}\n\nexport function shouldAutoEnableEditMode(options: InitOptions): boolean {\n  if (options.autoEnableEditFromQuery === false) {\n    return false;\n  }\n  return isEditModeQueryEnabled() && resolveEditToken(options) !== null;\n}\n","/**\n * Reads edit JWT claims without verification (M2-SDK-04).\n *\n * Intent: token was already issued by our API; overlay uses claims for env scoping only.\n */\nexport type EditTokenClaims = {\n  projectId: string;\n  applicationId: string;\n  environmentId: string;\n  environmentName: string;\n};\n\nexport function decodeEditTokenClaims(token: string): EditTokenClaims | null {\n  const parts = token.split(\".\");\n  if (parts.length < 2) {\n    return null;\n  }\n\n  try {\n    const payloadJson = base64UrlDecode(parts[1]!);\n    const payload = JSON.parse(payloadJson) as Record<string, unknown>;\n    const project = payload.project;\n    const app = payload.app;\n    const env = payload.env;\n    const envName = payload.envName;\n    if (\n      typeof project !== \"string\" ||\n      typeof app !== \"string\" ||\n      typeof env !== \"string\" ||\n      typeof envName !== \"string\"\n    ) {\n      return null;\n    }\n    return {\n      projectId: project,\n      applicationId: app,\n      environmentId: env,\n      environmentName: envName,\n    };\n  } catch {\n    return null;\n  }\n}\n\nfunction base64UrlDecode(segment: string): string {\n  const padded = segment.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const pad = padded.length % 4 === 0 ? \"\" : \"=\".repeat(4 - (padded.length % 4));\n  if (typeof atob === \"function\") {\n    return atob(padded + pad);\n  }\n  return Buffer.from(padded + pad, \"base64\").toString(\"utf8\");\n}\n"]}

package/dist/chunk-X3WTVBZ6.mjs

@@ -0,0 +1,153 @@
+// src/edit-token.ts
+var EDIT_TOKEN_QUERY_PARAM = "edit_token";
+var EDIT_MODE_QUERY_PARAM = "translation_edit";
+var EDIT_LAUNCHER_KEY_QUERY_PARAM = "translation_edit_key";
+var EDIT_TOKEN_STORAGE_KEY = "@translation/edit-token";
+function isEditModeQueryEnabled() {
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return false;
+  }
+  const params = new URLSearchParams(
+    globalThis.location.search
+  );
+  const value = params.get(EDIT_MODE_QUERY_PARAM);
+  return value === "1" || value === "true";
+}
+function readEditTokenFromQuery() {
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return null;
+  }
+  const params = new URLSearchParams(
+    globalThis.location.search
+  );
+  return params.get(EDIT_TOKEN_QUERY_PARAM);
+}
+function readEditTokenFromHash() {
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return null;
+  }
+  const hash = globalThis.location.hash;
+  if (!hash || hash.length <= 1) {
+    return null;
+  }
+  const params = new URLSearchParams(hash.startsWith("#") ? hash.slice(1) : hash);
+  return params.get(EDIT_TOKEN_QUERY_PARAM);
+}
+function isEditLauncherArmed(launcher) {
+  if (!isEditModeQueryEnabled()) {
+    return false;
+  }
+  if (!launcher?.armingKey) {
+    return true;
+  }
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return false;
+  }
+  const params = new URLSearchParams(
+    globalThis.location.search
+  );
+  return params.get(EDIT_LAUNCHER_KEY_QUERY_PARAM) === launcher.armingKey;
+}
+function readEditTokenFromStorage() {
+  if (typeof globalThis === "undefined" || !("sessionStorage" in globalThis)) {
+    return null;
+  }
+  try {
+    return globalThis.sessionStorage.getItem(
+      EDIT_TOKEN_STORAGE_KEY
+    ) ?? null;
+  } catch {
+    return null;
+  }
+}
+function persistEditToken(token) {
+  if (typeof globalThis === "undefined" || !("sessionStorage" in globalThis)) {
+    return;
+  }
+  try {
+    globalThis.sessionStorage.setItem(
+      EDIT_TOKEN_STORAGE_KEY,
+      token
+    );
+  } catch {
+  }
+}
+function resolveEditToken(options, override) {
+  const token = override ?? options.editToken ?? readEditTokenFromQuery() ?? readEditTokenFromHash() ?? readEditTokenFromStorage();
+  if (token) {
+    persistEditToken(token);
+  }
+  return token;
+}
+function stripEditTokenFromUrl() {
+  if (typeof globalThis === "undefined" || !("location" in globalThis)) {
+    return;
+  }
+  const win = globalThis;
+  const url = new URL(win.location.href);
+  url.searchParams.delete(EDIT_TOKEN_QUERY_PARAM);
+  if (url.hash) {
+    const hashParams = new URLSearchParams(url.hash.slice(1));
+    if (hashParams.has(EDIT_TOKEN_QUERY_PARAM)) {
+      hashParams.delete(EDIT_TOKEN_QUERY_PARAM);
+      const nextHash = hashParams.toString();
+      url.hash = nextHash ? `#${nextHash}` : "";
+    }
+  }
+  const next = `${url.pathname}${url.search}${url.hash}`;
+  win.history.replaceState(win.history.state, "", next);
+}
+function shouldAutoEnableEditMode(options) {
+  if (options.autoEnableEditFromQuery === false) {
+    return false;
+  }
+  return isEditModeQueryEnabled() && resolveEditToken(options) !== null;
+}
+
+// src/edit-token-decode.ts
+function decodeEditTokenClaims(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) {
+    return null;
+  }
+  try {
+    const payloadJson = base64UrlDecode(parts[1]);
+    const payload = JSON.parse(payloadJson);
+    const project = payload.project;
+    const app = payload.app;
+    const env = payload.env;
+    const envName = payload.envName;
+    if (typeof project !== "string" || typeof app !== "string" || typeof env !== "string" || typeof envName !== "string") {
+      return null;
+    }
+    return {
+      projectId: project,
+      applicationId: app,
+      environmentId: env,
+      environmentName: envName
+    };
+  } catch {
+    return null;
+  }
+}
+function base64UrlDecode(segment) {
+  const padded = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = padded.length % 4 === 0 ? "" : "=".repeat(4 - padded.length % 4);
+  if (typeof atob === "function") {
+    return atob(padded + pad);
+  }
+  return Buffer.from(padded + pad, "base64").toString("utf8");
+}
+
+export {
+  readEditTokenFromQuery,
+  readEditTokenFromHash,
+  isEditLauncherArmed,
+  readEditTokenFromStorage,
+  persistEditToken,
+  resolveEditToken,
+  stripEditTokenFromUrl,
+  shouldAutoEnableEditMode,
+  decodeEditTokenClaims
+};
+//# sourceMappingURL=chunk-X3WTVBZ6.mjs.map

package/dist/chunk-X3WTVBZ6.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/edit-token.ts","../src/edit-token-decode.ts"],"sourcesContent":["/**\n * Resolves overlay edit JWT from init options, URL, or sessionStorage (M2-SDK-01).\n */\nimport type { InitOptions } from \"./types.js\";\n\nexport const EDIT_TOKEN_QUERY_PARAM = \"edit_token\";\nexport const EDIT_MODE_QUERY_PARAM = \"translation_edit\";\nexport const EDIT_LAUNCHER_KEY_QUERY_PARAM = \"translation_edit_key\";\nexport const EDIT_TOKEN_STORAGE_KEY = \"@translation/edit-token\";\n\nexport function isEditModeQueryEnabled(): boolean {\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return false;\n  }\n  const params = new URLSearchParams(\n    (globalThis as Window & typeof globalThis).location.search,\n  );\n  const value = params.get(EDIT_MODE_QUERY_PARAM);\n  return value === \"1\" || value === \"true\";\n}\n\nexport function readEditTokenFromQuery(): string | null {\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return null;\n  }\n  const params = new URLSearchParams(\n    (globalThis as Window & typeof globalThis).location.search,\n  );\n  return params.get(EDIT_TOKEN_QUERY_PARAM);\n}\n\nexport function readEditTokenFromHash(): string | null {\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return null;\n  }\n  const hash = (globalThis as Window & typeof globalThis).location.hash;\n  if (!hash || hash.length <= 1) {\n    return null;\n  }\n  const params = new URLSearchParams(hash.startsWith(\"#\") ? hash.slice(1) : hash);\n  return params.get(EDIT_TOKEN_QUERY_PARAM);\n}\n\nexport function isEditLauncherArmed(launcher?: { armingKey?: string }): boolean {\n  if (!isEditModeQueryEnabled()) {\n    return false;\n  }\n  if (!launcher?.armingKey) {\n    return true;\n  }\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return false;\n  }\n  const params = new URLSearchParams(\n    (globalThis as Window & typeof globalThis).location.search,\n  );\n  return params.get(EDIT_LAUNCHER_KEY_QUERY_PARAM) === launcher.armingKey;\n}\n\nexport function readEditTokenFromStorage(): string | null {\n  if (typeof globalThis === \"undefined\" || !(\"sessionStorage\" in globalThis)) {\n    return null;\n  }\n  try {\n    return (\n      (globalThis as Window & typeof globalThis).sessionStorage.getItem(\n        EDIT_TOKEN_STORAGE_KEY,\n      ) ?? null\n    );\n  } catch {\n    return null;\n  }\n}\n\nexport function persistEditToken(token: string): void {\n  if (typeof globalThis === \"undefined\" || !(\"sessionStorage\" in globalThis)) {\n    return;\n  }\n  try {\n    (globalThis as Window & typeof globalThis).sessionStorage.setItem(\n      EDIT_TOKEN_STORAGE_KEY,\n      token,\n    );\n  } catch {\n    // Intent: private mode or blocked storage — overlay still works for this page load.\n  }\n}\n\nexport function resolveEditToken(\n  options: InitOptions,\n  override?: string,\n): string | null {\n  const token =\n    override ??\n    options.editToken ??\n    readEditTokenFromQuery() ??\n    readEditTokenFromHash() ??\n    readEditTokenFromStorage();\n  if (token) {\n    persistEditToken(token);\n  }\n  return token;\n}\n\n/**\n * Removes edit JWT from the URL after persisting to sessionStorage (M2-SDK-05).\n */\nexport function stripEditTokenFromUrl(): void {\n  if (typeof globalThis === \"undefined\" || !(\"location\" in globalThis)) {\n    return;\n  }\n  const win = globalThis as Window & typeof globalThis;\n  const url = new URL(win.location.href);\n  url.searchParams.delete(EDIT_TOKEN_QUERY_PARAM);\n  if (url.hash) {\n    const hashParams = new URLSearchParams(url.hash.slice(1));\n    if (hashParams.has(EDIT_TOKEN_QUERY_PARAM)) {\n      hashParams.delete(EDIT_TOKEN_QUERY_PARAM);\n      const nextHash = hashParams.toString();\n      url.hash = nextHash ? `#${nextHash}` : \"\";\n    }\n  }\n  const next = `${url.pathname}${url.search}${url.hash}`;\n  win.history.replaceState(win.history.state, \"\", next);\n}\n\nexport function shouldAutoEnableEditMode(options: InitOptions): boolean {\n  if (options.autoEnableEditFromQuery === false) {\n    return false;\n  }\n  return isEditModeQueryEnabled() && resolveEditToken(options) !== null;\n}\n","/**\n * Reads edit JWT claims without verification (M2-SDK-04).\n *\n * Intent: token was already issued by our API; overlay uses claims for env scoping only.\n */\nexport type EditTokenClaims = {\n  projectId: string;\n  applicationId: string;\n  environmentId: string;\n  environmentName: string;\n};\n\nexport function decodeEditTokenClaims(token: string): EditTokenClaims | null {\n  const parts = token.split(\".\");\n  if (parts.length < 2) {\n    return null;\n  }\n\n  try {\n    const payloadJson = base64UrlDecode(parts[1]!);\n    const payload = JSON.parse(payloadJson) as Record<string, unknown>;\n    const project = payload.project;\n    const app = payload.app;\n    const env = payload.env;\n    const envName = payload.envName;\n    if (\n      typeof project !== \"string\" ||\n      typeof app !== \"string\" ||\n      typeof env !== \"string\" ||\n      typeof envName !== \"string\"\n    ) {\n      return null;\n    }\n    return {\n      projectId: project,\n      applicationId: app,\n      environmentId: env,\n      environmentName: envName,\n    };\n  } catch {\n    return null;\n  }\n}\n\nfunction base64UrlDecode(segment: string): string {\n  const padded = segment.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const pad = padded.length % 4 === 0 ? \"\" : \"=\".repeat(4 - (padded.length % 4));\n  if (typeof atob === \"function\") {\n    return atob(padded + pad);\n  }\n  return Buffer.from(padded + pad, \"base64\").toString(\"utf8\");\n}\n"],"mappings":"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","names":[]}