@sonenta/astro 0.1.0

package/dist/runtime.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Public types for `@sonenta/astro` v0.1 (standalone, pre-core).
+ *
+ * FORWARD-COMPATIBILITY CONTRACT (frozen day-one — see CONTRACT.md): every
+ * option key here is the SAME key the future `@sonenta/i18n-core`-backed
+ * release will consume, so the later refactor (0.2.0) is a non-breaking,
+ * additive internal swap. New capabilities (surfaces, a11y accessors, CLDR
+ * plurals, variants) arrive ADDITIVELY; nothing here changes meaning.
+ */
+/** A BCP-47 locale code, e.g. `"fr"`, `"en"`, `"fr-CA"`. */
+type Locale = string;
+/** A bundle namespace (the `{ns}.json` file on the CDN), e.g. `"common"`. */
+type Namespace = string;
+/** Interpolation variables for a `t()` call: `t("greeting", { name: "Ada" })`. */
+type Vars = Record<string, string | number>;
+/** A resolved, per-locale translation function. */
+type TFn = (key: string, vars?: Vars) => string;
+/**
+ * Configuration for the Sonenta Astro integration / runtime.
+ *
+ * Bundles are fetched at BUILD time from
+ * `{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`
+ * (the canonical Sonenta CDN layout, identical to `@sonenta/react-i18next`).
+ */
+interface SonentaI18nOptions {
+    /** Project UUID from your Sonenta dashboard. Required. */
+    project: string;
+    /**
+     * Released version slug or pinned content hash. Default `"main"`.
+     * The CDN serves the latest release of this version under `/latest/`.
+     */
+    version?: string;
+    /**
+     * Locales to fetch and freeze into the static build. Required, non-empty.
+     * A locale whose bundle 404s (e.g. a plan-limit-blocked language) is kept
+     * as `null` and transparently falls back to the source language.
+     */
+    locales: Locale[];
+    /**
+     * Source / default locale. Default = `locales[0]`. Used as the implicit
+     * final fallback target and as Astro's source language.
+     */
+    defaultLocale?: Locale;
+    /**
+     * Ordered fallback chain applied when a key is missing in the active
+     * locale. Default = `[defaultLocale]`. v0.1 applies these locales in
+     * order; BCP-47 variant→base inheritance (`fr-CA → fr`) is deliberately
+     * left to the core-backed release.
+     */
+    fallbackLng?: Locale | Locale[];
+    /**
+     * Namespaces (bundle files) to fetch. Default `["common"]`. The first
+     * entry is the default namespace for un-prefixed keys; address others with
+     * the i18next-style `"ns:key"` syntax.
+     */
+    namespaces?: Namespace[];
+    /**
+     * CDN host root for translation bundles, WITHOUT the `/p` segment.
+     * Default `"https://cdn.sonenta.com"`. Overridable via the
+     * `SONENTA_CDN_BASE` env var (also a bare host; for local dev point it at
+     * your translation CDN). The `/p/{project}/{version}/latest/...` path is
+     * appended by the loader.
+     */
+    cdnBase?: string;
+    /**
+     * API host root. Reserved for forward-compatibility (the core-backed
+     * release uses it for the public language manifest and dev-mode runtime
+     * fetch). Default `"https://api.sonenta.dev"`. Unused by v0.1's prod
+     * build-time path.
+     */
+    apiBase?: string;
+    /**
+     * Injectable `fetch` implementation (testing / proxies / custom agents).
+     * Defaults to the global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * The resolved Sonenta i18n handle returned by `createSonentaI18n` and
+ * exposed through the `sonenta:i18n` virtual module.
+ */
+interface SonentaI18n {
+    /** Build a translation function bound to `locale`. */
+    getT(locale: Locale): TFn;
+    /** The locales that were fetched (the configured `locales`). */
+    readonly locales: Locale[];
+    /** The resolved source/default locale. */
+    readonly defaultLocale: Locale;
+    /**
+     * Raw fetched dictionary for `locale` / `namespace` (default namespace when
+     * omitted), or `null` when that bundle was absent (404 / plan-limit).
+     */
+    getCatalog(locale: Locale, namespace?: Namespace): Record<string, unknown> | null;
+}
+
+/**
+ * Build-time CDN loader for Sonenta translation bundles.
+ *
+ * Mirrors the canonical Sonenta CDN layout used by `@sonenta/react-i18next`:
+ *   `{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`
+ *
+ * Pure data fetch — no DOM, no React, no runtime. Called during `astro build`
+ * so the strings inline into the static HTML (zero client JS).
+ */
+
+/** A fetched bundle (a flat or nested dictionary of message strings). */
+type Bundle = Record<string, unknown>;
+/**
+ * Resolve the effective CDN host (no `/p`): explicit option wins, then the
+ * `SONENTA_CDN_BASE` env var, then the production default.
+ */
+declare function resolveCdnBase(opts: Pick<SonentaI18nOptions, "cdnBase">): string;
+/**
+ * Build the bundle URL for one `(locale, namespace)` pair.
+ * `{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`
+ */
+declare function buildBundleUrl(opts: Pick<SonentaI18nOptions, "project" | "version" | "cdnBase">, locale: Locale, namespace: Namespace): string;
+/**
+ * Fetch a single bundle. Resolves to `null` on 404 (locale absent from the
+ * project — e.g. a plan-limit-blocked language) so callers fall back to the
+ * source language. Any other non-OK status or transport error throws so a
+ * misconfigured build fails loudly rather than silently shipping empty pages.
+ */
+declare function fetchBundle(opts: Pick<SonentaI18nOptions, "project" | "version" | "cdnBase" | "fetchImpl">, locale: Locale, namespace: Namespace): Promise<Bundle | null>;
+/**
+ * Fetch one namespace across every locale, in parallel. Absent locales map to
+ * `null`. Returns `Record<Locale, Bundle | null>`.
+ */
+declare function fetchNamespace(opts: Pick<SonentaI18nOptions, "project" | "version" | "cdnBase" | "fetchImpl">, locales: Locale[], namespace: Namespace): Promise<Record<Locale, Bundle | null>>;
+/**
+ * Fetch every `(locale, namespace)` pair. Returns a nested map keyed by
+ * locale then namespace: `data[locale][namespace] = Bundle | null`.
+ */
+declare function fetchAll(opts: Pick<SonentaI18nOptions, "project" | "version" | "cdnBase" | "fetchImpl">, locales: Locale[], namespaces: Namespace[]): Promise<Record<Locale, Record<Namespace, Bundle | null>>>;
+
+/**
+ * Build-time translation resolver.
+ *
+ * v0.1 SCOPE (frozen — see CONTRACT.md): string resolution + `{var}`
+ * interpolation + source-language fallback ONLY. Deliberately NO CLDR
+ * plurals, NO surfaces, NO a11y accessors, NO BCP-47 variant→base
+ * inheritance — those carry real i18n SEMANTICS owned by `@sonenta/i18n-core`
+ * and arrive additively in 0.2.0. Keeping them out of v0.1 means there is no
+ * naive semantics to break when the core swaps in underneath this same API.
+ */
+
+/**
+ * Build a `t()` bound to `locale`, given the fetched data and resolution
+ * order. Lookup: active locale's namespace dict → each fallback locale's same
+ * namespace dict → the raw key (i18next-parity missing-key behaviour).
+ */
+declare function createT(data: Record<Locale, Record<Namespace, Bundle | null>>, locale: Locale, fallbackChain: Locale[], defaultNamespace: Namespace): TFn;
+/**
+ * Fetch every configured bundle at build time and return a resolved
+ * {@link SonentaI18n} handle. Call once (top-level `await`) and reuse its
+ * `getT(locale)` across pages.
+ */
+declare function createSonentaI18n(options: SonentaI18nOptions): Promise<SonentaI18n>;
+
+export { type Bundle, type Locale, type Namespace, type SonentaI18n, type SonentaI18nOptions, type TFn, type Vars, buildBundleUrl, createSonentaI18n, createT, fetchAll, fetchBundle, fetchNamespace, resolveCdnBase };

package/dist/runtime.js

@@ -0,0 +1,19 @@
+import {
+  buildBundleUrl,
+  createSonentaI18n,
+  createT,
+  fetchAll,
+  fetchBundle,
+  fetchNamespace,
+  resolveCdnBase
+} from "./chunk-CK2DAB6G.js";
+export {
+  buildBundleUrl,
+  createSonentaI18n,
+  createT,
+  fetchAll,
+  fetchBundle,
+  fetchNamespace,
+  resolveCdnBase
+};
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@sonenta/astro",
+  "version": "0.1.0",
+  "description": "Official Astro integration for Sonenta i18n — build-time CDN translations, zero client JS (SSG).",
+  "license": "MIT",
+  "homepage": "https://sonenta.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sonenta/sdk.git",
+    "directory": "packages/astro"
+  },
+  "keywords": [
+    "i18n",
+    "translations",
+    "astro",
+    "astro-integration",
+    "astro-component",
+    "ssg",
+    "sonenta"
+  ],
+  "author": "Sonenta",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js",
+      "require": "./dist/runtime.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CONTRACT.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "astro": "^5.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "pack:dry-run": "pnpm pack --dry-run"
+  }
+}