@stringpush/runtime-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,170 @@
+/**
+ * Runtime-core public types — shared by @stringpush/sdk and future framework adapters (M14-CORE-01).
+ *
+ * Intent: no overlay/edit fields; adapters extend this shape in their own packages.
+ */
+type Environment = "dev" | "staging" | "production";
+type ManifestLocaleEntry = {
+    version: number;
+    url: string;
+    contentHash: string;
+};
+/** Manifest returned by `GET /v1/applications/:id/manifest`. */
+type TranslationManifest = {
+    projectId: string;
+    applicationId: string;
+    environment: Environment;
+    locales: Record<string, ManifestLocaleEntry>;
+};
+type RetryOptions = {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+};
+type ReportUsageOptions = boolean | {
+    storageKey?: string;
+};
+type RuntimeInitOptions = {
+    /** SDK install target (application id from admin). */
+    applicationId: string;
+    environment: Environment;
+    locale: string;
+    /** Runtime API key (`trt_…`). */
+    apiKey: string;
+    /** API origin, e.g. `https://api.example.com` (defaults to `window.location.origin` in browsers). */
+    apiBaseUrl?: string;
+    /** Sent as `Origin` for runtime key allowlist checks (defaults to `window.location.origin`). */
+    origin?: string;
+    fetch?: typeof fetch;
+    retry?: RetryOptions;
+    onLocaleChange?: (locale: string) => void;
+    onTranslationsUpdated?: () => void;
+    /**
+     * When a key is missing from the CDN catalog. Bundles already embed `default_message`
+     * for keys without a published value; use `default_message` + `defaultMessages` for
+     * keys not present in the bundle at all.
+     */
+    missingKeyFallback?: MissingKeyFallback;
+    /** Lookup for `missingKeyFallback: "default_message"` (keys not in the bundle). */
+    defaultMessages?: Record<string, string>;
+    /**
+     * When enabled, sends an anonymous MAU beacon after init (`POST /v1/usage/mau`).
+     * Intent: counts unique visitors per org/month via SHA-256 hash only — no PII leaves the client.
+     */
+    reportUsage?: ReportUsageOptions;
+};
+type TranslationCatalog = Record<string, string>;
+/** How `t()` behaves when a key is absent from the loaded catalog. */
+type MissingKeyFallback = "key" | "default_message" | "empty";
+/** Values passed to `t(key, values)` for ICU interpolation and plurals. */
+type TranslateValues = Record<string, unknown>;
+
+type SdkRuntime = {
+    options: RuntimeInitOptions | null;
+    manifest: TranslationManifest | null;
+    catalog: TranslationCatalog;
+    locale: string;
+};
+declare function getRuntime(): SdkRuntime;
+declare function resetRuntime(): void;
+declare function assertInitialized(): RuntimeInitOptions;
+
+/**
+ * Loads manifest + active locale bundle into memory and optionally reports MAU.
+ */
+declare function initializeRuntime(options: RuntimeInitOptions): Promise<void>;
+declare function destroyRuntime(): void;
+declare function getRuntimeLocale(): string;
+/**
+ * Switch active locale and reload its bundle from the manifest.
+ */
+declare function changeLocale(locale: string): Promise<void>;
+/**
+ * Translate a key using the loaded catalog and ICU MessageFormat.
+ */
+declare function translateKey(key: string, values?: TranslateValues): string;
+
+type FetchBundleOptions = {
+    /** When set, a 304 response returns this catalog instead of `{}`. */
+    fallbackCatalog?: TranslationCatalog;
+    cache?: RequestCache;
+};
+declare function fetchManifest(options: RuntimeInitOptions, fetchFn: typeof fetch): Promise<TranslationManifest>;
+declare function fetchBundle(options: RuntimeInitOptions, manifest: TranslationManifest, locale: string, fetchFn: typeof fetch, bundleOptions?: FetchBundleOptions): Promise<TranslationCatalog>;
+
+/**
+ * Resilient fetch for manifest and bundle loads.
+ *
+ * Intent: retry network errors and 5xx only; 4xx fail fast so misconfiguration surfaces clearly.
+ */
+
+/**
+ * Fetches with exponential backoff on network errors and 5xx responses.
+ */
+declare function fetchWithRetry(input: RequestInfo | URL, init: RequestInit | undefined, fetchFn: typeof fetch, retry?: RetryOptions): Promise<Response>;
+
+/**
+ * URL builders and runtime auth headers for API delivery routes.
+ *
+ * Intent: resolve relative bundle paths from manifest against `apiBaseUrl`; set Origin for allowlist.
+ */
+
+declare function resolveApiBaseUrl(apiBaseUrl: string | undefined): string;
+declare function resolveRequestOrigin(origin: string | undefined): string | undefined;
+declare function buildManifestUrl(apiBaseUrl: string, applicationId: string, environment: Environment): string;
+declare function resolveBundleUrl(apiBaseUrl: string, bundlePath: string): string;
+/** True when the manifest points at a CDN (or BYO) origin separate from the API. */
+declare function isCrossOriginBundleUrl(apiBaseUrl: string, bundleUrl: string): boolean;
+/**
+ * Bundle fetch options: runtime auth only when bundles are served from the API origin.
+ *
+ * Intent: CDN bundles are public immutable JSON — sending Authorization triggers CORS
+ * preflight and wrongly treats the delivery plane like the control plane.
+ */
+declare function bundleFetchInit(options: RuntimeInitOptions, apiBaseUrl: string, resolvedBundleUrl: string): RequestInit;
+declare function runtimeFetchInit(options: RuntimeInitOptions): RequestInit;
+
+/**
+ * Formats a catalog template with optional ICU values for the active locale.
+ */
+declare function formatMessage(template: string, locale: string, values?: Record<string, unknown>): string;
+/**
+ * Resolves the message template for a key before ICU formatting.
+ */
+declare function resolveTemplate(key: string, catalog: TranslationCatalog, options: Pick<RuntimeInitOptions, "missingKeyFallback" | "defaultMessages">): string;
+
+declare function valueVersionKey(keyPath: string, localeCode: string): string;
+declare function getRecordedVersion(keyPath: string, localeCode: string): number | undefined;
+declare function shouldApplyTranslationUpdate(keyPath: string, localeCode: string, version: number): boolean;
+declare function recordTranslationVersion(keyPath: string, localeCode: string, version: number): void;
+declare function clearCatalogVersions(): void;
+
+declare function patchCatalogEntry(keyPath: string, localeCode: string, value: string, version?: number): boolean;
+
+/**
+ * Reloads manifest and the active locale bundle from the API/CDN.
+ */
+declare function reloadManifestAndActiveLocale(): Promise<boolean>;
+/**
+ * When `bundle.published` reports a newer bundle for the active locale, refetch manifest + bundle.
+ */
+declare function reloadIfBundlePublishedNewer(releases: Array<{
+    localeCode: string;
+    bundleVersion: number;
+}>): Promise<boolean>;
+
+/**
+ * Sends one MAU ping for the current calendar month (idempotent server-side per visitor hash).
+ */
+declare function reportUsageBeacon(options: RuntimeInitOptions): void;
+
+/**
+ * Anonymous visitor id for MAU beacons (M6-MAU-01).
+ *
+ * Intent: stable random id in localStorage; only SHA-256 hash is sent to the API.
+ */
+declare const DEFAULT_VISITOR_STORAGE_KEY = "@stringpush/sdk/visitor-id";
+declare function getOrCreateVisitorId(storageKey?: string): string | null;
+declare function hashVisitorId(visitorId: string): Promise<string>;
+
+export { DEFAULT_VISITOR_STORAGE_KEY, type Environment, type FetchBundleOptions, type ManifestLocaleEntry, type MissingKeyFallback, type ReportUsageOptions, type RetryOptions, type RuntimeInitOptions, type SdkRuntime, type TranslateValues, type TranslationCatalog, type TranslationManifest, assertInitialized, buildManifestUrl, bundleFetchInit, changeLocale, clearCatalogVersions, destroyRuntime, fetchBundle, fetchManifest, fetchWithRetry, formatMessage, getOrCreateVisitorId, getRecordedVersion, getRuntime, getRuntimeLocale, hashVisitorId, initializeRuntime, isCrossOriginBundleUrl, patchCatalogEntry, recordTranslationVersion, reloadIfBundlePublishedNewer, reloadManifestAndActiveLocale, reportUsageBeacon, resetRuntime, resolveApiBaseUrl, resolveBundleUrl, resolveRequestOrigin, resolveTemplate, runtimeFetchInit, shouldApplyTranslationUpdate, translateKey, valueVersionKey };

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Runtime-core public types — shared by @stringpush/sdk and future framework adapters (M14-CORE-01).
+ *
+ * Intent: no overlay/edit fields; adapters extend this shape in their own packages.
+ */
+type Environment = "dev" | "staging" | "production";
+type ManifestLocaleEntry = {
+    version: number;
+    url: string;
+    contentHash: string;
+};
+/** Manifest returned by `GET /v1/applications/:id/manifest`. */
+type TranslationManifest = {
+    projectId: string;
+    applicationId: string;
+    environment: Environment;
+    locales: Record<string, ManifestLocaleEntry>;
+};
+type RetryOptions = {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+};
+type ReportUsageOptions = boolean | {
+    storageKey?: string;
+};
+type RuntimeInitOptions = {
+    /** SDK install target (application id from admin). */
+    applicationId: string;
+    environment: Environment;
+    locale: string;
+    /** Runtime API key (`trt_…`). */
+    apiKey: string;
+    /** API origin, e.g. `https://api.example.com` (defaults to `window.location.origin` in browsers). */
+    apiBaseUrl?: string;
+    /** Sent as `Origin` for runtime key allowlist checks (defaults to `window.location.origin`). */
+    origin?: string;
+    fetch?: typeof fetch;
+    retry?: RetryOptions;
+    onLocaleChange?: (locale: string) => void;
+    onTranslationsUpdated?: () => void;
+    /**
+     * When a key is missing from the CDN catalog. Bundles already embed `default_message`
+     * for keys without a published value; use `default_message` + `defaultMessages` for
+     * keys not present in the bundle at all.
+     */
+    missingKeyFallback?: MissingKeyFallback;
+    /** Lookup for `missingKeyFallback: "default_message"` (keys not in the bundle). */
+    defaultMessages?: Record<string, string>;
+    /**
+     * When enabled, sends an anonymous MAU beacon after init (`POST /v1/usage/mau`).
+     * Intent: counts unique visitors per org/month via SHA-256 hash only — no PII leaves the client.
+     */
+    reportUsage?: ReportUsageOptions;
+};
+type TranslationCatalog = Record<string, string>;
+/** How `t()` behaves when a key is absent from the loaded catalog. */
+type MissingKeyFallback = "key" | "default_message" | "empty";
+/** Values passed to `t(key, values)` for ICU interpolation and plurals. */
+type TranslateValues = Record<string, unknown>;
+
+type SdkRuntime = {
+    options: RuntimeInitOptions | null;
+    manifest: TranslationManifest | null;
+    catalog: TranslationCatalog;
+    locale: string;
+};
+declare function getRuntime(): SdkRuntime;
+declare function resetRuntime(): void;
+declare function assertInitialized(): RuntimeInitOptions;
+
+/**
+ * Loads manifest + active locale bundle into memory and optionally reports MAU.
+ */
+declare function initializeRuntime(options: RuntimeInitOptions): Promise<void>;
+declare function destroyRuntime(): void;
+declare function getRuntimeLocale(): string;
+/**
+ * Switch active locale and reload its bundle from the manifest.
+ */
+declare function changeLocale(locale: string): Promise<void>;
+/**
+ * Translate a key using the loaded catalog and ICU MessageFormat.
+ */
+declare function translateKey(key: string, values?: TranslateValues): string;
+
+type FetchBundleOptions = {
+    /** When set, a 304 response returns this catalog instead of `{}`. */
+    fallbackCatalog?: TranslationCatalog;
+    cache?: RequestCache;
+};
+declare function fetchManifest(options: RuntimeInitOptions, fetchFn: typeof fetch): Promise<TranslationManifest>;
+declare function fetchBundle(options: RuntimeInitOptions, manifest: TranslationManifest, locale: string, fetchFn: typeof fetch, bundleOptions?: FetchBundleOptions): Promise<TranslationCatalog>;
+
+/**
+ * Resilient fetch for manifest and bundle loads.
+ *
+ * Intent: retry network errors and 5xx only; 4xx fail fast so misconfiguration surfaces clearly.
+ */
+
+/**
+ * Fetches with exponential backoff on network errors and 5xx responses.
+ */
+declare function fetchWithRetry(input: RequestInfo | URL, init: RequestInit | undefined, fetchFn: typeof fetch, retry?: RetryOptions): Promise<Response>;
+
+/**
+ * URL builders and runtime auth headers for API delivery routes.
+ *
+ * Intent: resolve relative bundle paths from manifest against `apiBaseUrl`; set Origin for allowlist.
+ */
+
+declare function resolveApiBaseUrl(apiBaseUrl: string | undefined): string;
+declare function resolveRequestOrigin(origin: string | undefined): string | undefined;
+declare function buildManifestUrl(apiBaseUrl: string, applicationId: string, environment: Environment): string;
+declare function resolveBundleUrl(apiBaseUrl: string, bundlePath: string): string;
+/** True when the manifest points at a CDN (or BYO) origin separate from the API. */
+declare function isCrossOriginBundleUrl(apiBaseUrl: string, bundleUrl: string): boolean;
+/**
+ * Bundle fetch options: runtime auth only when bundles are served from the API origin.
+ *
+ * Intent: CDN bundles are public immutable JSON — sending Authorization triggers CORS
+ * preflight and wrongly treats the delivery plane like the control plane.
+ */
+declare function bundleFetchInit(options: RuntimeInitOptions, apiBaseUrl: string, resolvedBundleUrl: string): RequestInit;
+declare function runtimeFetchInit(options: RuntimeInitOptions): RequestInit;
+
+/**
+ * Formats a catalog template with optional ICU values for the active locale.
+ */
+declare function formatMessage(template: string, locale: string, values?: Record<string, unknown>): string;
+/**
+ * Resolves the message template for a key before ICU formatting.
+ */
+declare function resolveTemplate(key: string, catalog: TranslationCatalog, options: Pick<RuntimeInitOptions, "missingKeyFallback" | "defaultMessages">): string;
+
+declare function valueVersionKey(keyPath: string, localeCode: string): string;
+declare function getRecordedVersion(keyPath: string, localeCode: string): number | undefined;
+declare function shouldApplyTranslationUpdate(keyPath: string, localeCode: string, version: number): boolean;
+declare function recordTranslationVersion(keyPath: string, localeCode: string, version: number): void;
+declare function clearCatalogVersions(): void;
+
+declare function patchCatalogEntry(keyPath: string, localeCode: string, value: string, version?: number): boolean;
+
+/**
+ * Reloads manifest and the active locale bundle from the API/CDN.
+ */
+declare function reloadManifestAndActiveLocale(): Promise<boolean>;
+/**
+ * When `bundle.published` reports a newer bundle for the active locale, refetch manifest + bundle.
+ */
+declare function reloadIfBundlePublishedNewer(releases: Array<{
+    localeCode: string;
+    bundleVersion: number;
+}>): Promise<boolean>;
+
+/**
+ * Sends one MAU ping for the current calendar month (idempotent server-side per visitor hash).
+ */
+declare function reportUsageBeacon(options: RuntimeInitOptions): void;
+
+/**
+ * Anonymous visitor id for MAU beacons (M6-MAU-01).
+ *
+ * Intent: stable random id in localStorage; only SHA-256 hash is sent to the API.
+ */
+declare const DEFAULT_VISITOR_STORAGE_KEY = "@stringpush/sdk/visitor-id";
+declare function getOrCreateVisitorId(storageKey?: string): string | null;
+declare function hashVisitorId(visitorId: string): Promise<string>;
+
+export { DEFAULT_VISITOR_STORAGE_KEY, type Environment, type FetchBundleOptions, type ManifestLocaleEntry, type MissingKeyFallback, type ReportUsageOptions, type RetryOptions, type RuntimeInitOptions, type SdkRuntime, type TranslateValues, type TranslationCatalog, type TranslationManifest, assertInitialized, buildManifestUrl, bundleFetchInit, changeLocale, clearCatalogVersions, destroyRuntime, fetchBundle, fetchManifest, fetchWithRetry, formatMessage, getOrCreateVisitorId, getRecordedVersion, getRuntime, getRuntimeLocale, hashVisitorId, initializeRuntime, isCrossOriginBundleUrl, patchCatalogEntry, recordTranslationVersion, reloadIfBundlePublishedNewer, reloadManifestAndActiveLocale, reportUsageBeacon, resetRuntime, resolveApiBaseUrl, resolveBundleUrl, resolveRequestOrigin, resolveTemplate, runtimeFetchInit, shouldApplyTranslationUpdate, translateKey, valueVersionKey };