@krizaka/app-config 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @krizaka/app-config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+App version compatibility between Krizaka apps (React Native, the Mac app, the web) and their backends. One contract,
+two implementations: this package (Next.js backends and clients) and the Java building block
+[`krizaka-app-config`](https://github.com/krizaka/krizaka-platform-kit/tree/main/krizaka-app-config), both passing the
+same fixture (`test/cases.json`) and sharing one JSON schema (`contract/app-config.schema.json`). Zero dependency.
+
+| Entry | For |
+|:---|:---|
+| `@krizaka/app-config` | the contract, pure: versions, the payload, `evaluateGuard`, `validateRecord` |
+| `@krizaka/app-config/server` | Next.js backends: `createAppConfigHandler`, `checkClientVersion`, `withClientVersionGuard`, `cachedStore`, `memoryStore`, `schemaSql` (the tables) |
+| `@krizaka/app-config/client` | apps: `createAppConfigClient` (launch + resume checks, soft dismissal, the global 426 interceptor `client.fetch`), `decide` |
+| `@krizaka/app-config/react` | `useAppConfig`, `appStateResume(AppState)`, `visibilityResume(document)` |
+
+The screens are in `@krizaka/ui`: `UpdatePrompt`, `ForceUpdateScreen`, `MaintenanceScreen` (web and `/native`).
+Documentation: <https://ui.krizaka.com/packages/app-config>.

package/contract/app-config.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://krizaka.com/contracts/app-config.schema.json",
+  "title": "Krizaka app-config payload",
+  "description": "The body of GET /api/v1/app-config and the appConfig member of a 426 Upgrade Required problem. Shared by the Java building block krizaka-app-config and the TypeScript package @krizaka/app-config.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "platform",
+    "minSupportedVersion",
+    "latestVersion",
+    "updateMode",
+    "storeUrl",
+    "maintenance",
+    "contract",
+    "flags",
+    "message",
+    "locale"
+  ],
+  "properties": {
+    "platform": { "enum": ["ios", "android", "macos", "windows", "linux", "web"] },
+    "minSupportedVersion": { "$ref": "#/$defs/version" },
+    "latestVersion": { "$ref": "#/$defs/version" },
+    "updateMode": { "enum": ["none", "soft", "force"] },
+    "storeUrl": { "type": ["string", "null"], "pattern": "^https://" },
+    "maintenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["on", "message"],
+      "properties": {
+        "on": { "type": "boolean" },
+        "message": { "type": ["string", "null"], "maxLength": 500 }
+      }
+    },
+    "contract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["min", "max", "sunset"],
+      "properties": {
+        "min": { "type": "integer", "minimum": 1 },
+        "max": { "type": "integer", "minimum": 1 },
+        "sunset": { "type": ["string", "null"], "format": "date" }
+      }
+    },
+    "flags": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9._-]{0,63}$" },
+      "additionalProperties": { "type": ["boolean", "number", "string"] }
+    },
+    "message": { "type": ["string", "null"], "maxLength": 500 },
+    "locale": { "type": "string", "pattern": "^[a-z]{2}$" }
+  },
+  "$defs": {
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }
+  }
+}

package/contract/krizaka-app-config-schema.sql

@@ -0,0 +1,57 @@
+-- krizaka-app-config: the parameters of the app-version contract, one row per platform.
+-- Version 1 is seeded here (permissive: no minimum, no maintenance, one contract); a product's own
+-- migration publishes its real values through the admin API, never by editing the row by hand.
+CREATE TABLE IF NOT EXISTS app_config (
+    platform              VARCHAR(16)  PRIMARY KEY,
+    min_supported_version VARCHAR(32)  NOT NULL DEFAULT '0.0.0',
+    latest_version        VARCHAR(32)  NOT NULL DEFAULT '0.0.0',
+    update_override       VARCHAR(8),
+    store_url             TEXT,
+    maintenance_on        BOOLEAN      NOT NULL DEFAULT FALSE,
+    maintenance_message   JSONB        NOT NULL DEFAULT '{}'::jsonb,
+    message               JSONB        NOT NULL DEFAULT '{}'::jsonb,
+    contract_min          INTEGER      NOT NULL DEFAULT 1,
+    contract_max          INTEGER      NOT NULL DEFAULT 1,
+    contract_sunset       DATE,
+    flags                 JSONB        NOT NULL DEFAULT '{}'::jsonb,
+    revision              INTEGER      NOT NULL DEFAULT 1,
+    updated_at            TIMESTAMPTZ  NOT NULL DEFAULT now(),
+    updated_by            VARCHAR(255) NOT NULL DEFAULT 'seed',
+    CONSTRAINT app_config_platform_known CHECK (platform IN ('ios', 'android', 'macos', 'windows', 'linux', 'web')),
+    CONSTRAINT app_config_contract_range CHECK (contract_min >= 1 AND contract_max >= contract_min)
+);
+
+-- Every published revision, append-only: the audit trail and the source of a rollback.
+CREATE TABLE IF NOT EXISTS app_config_history (
+    id                    BIGSERIAL    PRIMARY KEY,
+    platform              VARCHAR(16)  NOT NULL,
+    revision              INTEGER      NOT NULL,
+    min_supported_version VARCHAR(32)  NOT NULL,
+    latest_version        VARCHAR(32)  NOT NULL,
+    update_override       VARCHAR(8),
+    store_url             TEXT,
+    maintenance_on        BOOLEAN      NOT NULL,
+    maintenance_message   JSONB        NOT NULL,
+    message               JSONB        NOT NULL,
+    contract_min          INTEGER      NOT NULL,
+    contract_max          INTEGER      NOT NULL,
+    contract_sunset       DATE,
+    flags                 JSONB        NOT NULL,
+    reason                TEXT         NOT NULL,
+    changed_by            VARCHAR(255) NOT NULL,
+    changed_at            TIMESTAMPTZ  NOT NULL DEFAULT now(),
+    CONSTRAINT app_config_history_revision UNIQUE (platform, revision)
+);
+
+INSERT INTO app_config (platform)
+VALUES ('ios'), ('android'), ('macos'), ('windows'), ('linux'), ('web')
+ON CONFLICT (platform) DO NOTHING;
+
+INSERT INTO app_config_history (platform, revision, min_supported_version, latest_version, update_override,
+                                store_url, maintenance_on, maintenance_message, message, contract_min,
+                                contract_max, contract_sunset, flags, reason, changed_by, changed_at)
+SELECT platform, revision, min_supported_version, latest_version, update_override, store_url, maintenance_on,
+       maintenance_message, message, contract_min, contract_max, contract_sunset, flags, 'seed', updated_by,
+       updated_at
+FROM app_config
+ON CONFLICT (platform, revision) DO NOTHING;

package/dist/chunk-D3DIU5IW.js

@@ -0,0 +1,152 @@
+// src/core.ts
+var PLATFORMS = ["ios", "android", "macos", "windows", "linux", "web"];
+var UPDATE_MODES = ["none", "soft", "force"];
+var CLIENT_HEADERS = {
+  version: "X-Client-Version",
+  platform: "X-Client-Platform",
+  contract: "X-Contract-Version",
+  build: "X-Client-Build",
+  deprecation: "Deprecation",
+  sunset: "Sunset"
+};
+var APP_CONFIG_PATH = "/api/v1/app-config";
+var VERSION = /^v?(\d{1,6})(?:\.(\d{1,6}))?(?:\.(\d{1,6}))?(?:[-+].*)?$/;
+function parseVersion(text) {
+  const match = VERSION.exec((text ?? "").trim());
+  return match ? [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)] : null;
+}
+function compareVersions(a, b) {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+function formatVersion(version) {
+  return version.join(".");
+}
+var ZERO = [0, 0, 0];
+function isPlatform(value) {
+  return typeof value === "string" && PLATFORMS.includes(value.trim().toLowerCase());
+}
+function toPlatform(value) {
+  const wanted = (value ?? "").trim().toLowerCase();
+  return isPlatform(wanted) ? wanted : null;
+}
+function defaultRecord(platform) {
+  return {
+    platform,
+    minSupportedVersion: "0.0.0",
+    latestVersion: "0.0.0",
+    updateOverride: null,
+    storeUrl: null,
+    maintenanceOn: false,
+    maintenanceMessage: {},
+    message: {},
+    contractMin: 1,
+    contractMax: 1,
+    contractSunset: null,
+    flags: {},
+    revision: 1,
+    updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+    updatedBy: "seed"
+  };
+}
+var LANGUAGE = /^[a-z]{2}$/;
+var FLAG_KEY = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;
+var MAX_TEXT = 500;
+function checkTexts(field, texts) {
+  return Object.entries(texts).flatMap(([language, text]) => {
+    if (!LANGUAGE.test(language)) return [`${field} language must be two letters: ${language}`];
+    return text.length > MAX_TEXT ? [`${field}.${language} is too long`] : [];
+  });
+}
+function validateRecord(record) {
+  const problems = [];
+  const min = parseVersion(record.minSupportedVersion);
+  const latest = parseVersion(record.latestVersion);
+  if (!min || !latest) problems.push("versions must look like 1.4.0");
+  else if (compareVersions(latest, min) < 0) problems.push("latestVersion is older than minSupportedVersion");
+  if (!Number.isInteger(record.contractMin) || record.contractMin < 1 || record.contractMax < record.contractMin) {
+    problems.push("contract range must satisfy 1 <= min <= max");
+  }
+  if (record.storeUrl !== null && !/^https:\/\/[^\s/]+/.test(record.storeUrl)) problems.push("storeUrl must be an absolute https URL");
+  problems.push(...checkTexts("message", record.message), ...checkTexts("maintenanceMessage", record.maintenanceMessage));
+  for (const [key, value] of Object.entries(record.flags)) {
+    if (!FLAG_KEY.test(key)) problems.push(`flag key not allowed: ${key}`);
+    if (!["boolean", "number", "string"].includes(typeof value)) problems.push(`flag ${key} must be a boolean, number or string`);
+  }
+  return problems;
+}
+function updateModeFor(record, client) {
+  if (record.updateOverride) return record.updateOverride;
+  if (!client) return "none";
+  if (compareVersions(client, parseVersion(record.minSupportedVersion) ?? ZERO) < 0) return "force";
+  return compareVersions(client, parseVersion(record.latestVersion) ?? ZERO) < 0 ? "soft" : "none";
+}
+function pickLanguage(wanted, ...texts) {
+  const language = (wanted ?? "en").toLowerCase();
+  return texts.some((t) => language in t) ? language : "en";
+}
+function buildPayload(record, client, language) {
+  const chosen = pickLanguage(language, record.message, record.maintenanceMessage);
+  const text = (texts) => texts[chosen] ?? texts.en ?? null;
+  return {
+    platform: record.platform,
+    minSupportedVersion: formatVersion(parseVersion(record.minSupportedVersion) ?? ZERO),
+    latestVersion: formatVersion(parseVersion(record.latestVersion) ?? ZERO),
+    updateMode: updateModeFor(record, client),
+    storeUrl: record.storeUrl,
+    maintenance: { on: record.maintenanceOn, message: text(record.maintenanceMessage) },
+    contract: { min: record.contractMin, max: record.contractMax, sunset: record.contractSunset },
+    flags: record.flags,
+    message: text(record.message),
+    locale: chosen
+  };
+}
+function contractOf(value) {
+  const n = typeof value === "number" ? value : Number.parseInt(String(value ?? "").trim(), 10);
+  return Number.isInteger(n) && n >= 1 ? n : null;
+}
+function sunsetDate(day) {
+  const [y, m, d] = day.split("-").map(Number);
+  return new Date(Date.UTC(y, m - 1, d + 1)).toUTCString();
+}
+function evaluateGuard(record, client) {
+  const version = parseVersion(client.version);
+  const contract = contractOf(client.contract);
+  const base = { deprecation: false, contract: record.contractMax };
+  const tooOld = version !== null && compareVersions(version, parseVersion(record.minSupportedVersion) ?? ZERO) < 0;
+  const contractGone = contract !== null && contract < record.contractMin;
+  if (tooOld || contractGone) {
+    const payload = { ...buildPayload(record, version, client.language), updateMode: "force" };
+    return { ...base, status: 426, code: tooOld ? "upgrade-required" : "contract-unsupported", payload };
+  }
+  if (contract !== null && contract < record.contractMax) {
+    return { ...base, status: 200, deprecation: true, ...record.contractSunset ? { sunset: sunsetDate(record.contractSunset) } : {} };
+  }
+  return { ...base, status: 200 };
+}
+var SEMVER = /^\d+\.\d+\.\d+$/;
+function isAppConfigPayload(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  const maintenance = v.maintenance;
+  const contract = v.contract;
+  return isPlatform(v.platform) && typeof v.minSupportedVersion === "string" && SEMVER.test(v.minSupportedVersion) && typeof v.latestVersion === "string" && SEMVER.test(v.latestVersion) && UPDATE_MODES.includes(v.updateMode) && typeof maintenance === "object" && typeof maintenance?.on === "boolean" && typeof contract === "object" && typeof contract?.min === "number" && typeof contract?.max === "number";
+}
+
+export {
+  PLATFORMS,
+  UPDATE_MODES,
+  CLIENT_HEADERS,
+  APP_CONFIG_PATH,
+  parseVersion,
+  compareVersions,
+  formatVersion,
+  isPlatform,
+  toPlatform,
+  defaultRecord,
+  validateRecord,
+  updateModeFor,
+  buildPayload,
+  evaluateGuard,
+  isAppConfigPayload
+};
+//# sourceMappingURL=chunk-D3DIU5IW.js.map

package/dist/chunk-D3DIU5IW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core.ts"],"sourcesContent":["/**\n * The contract, pure: versions, the payload, and the rules that decide what happens to a client.\n * Twin of the Java building block `krizaka-app-config`; `test/cases.json` is the fixture both obey.\n */\n\nexport const PLATFORMS = [\"ios\", \"android\", \"macos\", \"windows\", \"linux\", \"web\"] as const;\nexport type Platform = (typeof PLATFORMS)[number];\n\nexport const UPDATE_MODES = [\"none\", \"soft\", \"force\"] as const;\nexport type UpdateMode = (typeof UPDATE_MODES)[number];\n\n/** The headers an app sends and the backend answers with. */\nexport const CLIENT_HEADERS = {\n  version: \"X-Client-Version\",\n  platform: \"X-Client-Platform\",\n  contract: \"X-Contract-Version\",\n  build: \"X-Client-Build\",\n  deprecation: \"Deprecation\",\n  sunset: \"Sunset\",\n} as const;\n\n/** The public endpoint's path. */\nexport const APP_CONFIG_PATH = \"/api/v1/app-config\";\n\nexport type FlagValue = boolean | number | string;\n\n/** What `GET /api/v1/app-config` returns and what a `426` carries as `appConfig`. */\nexport interface AppConfigPayload {\n  platform: Platform;\n  minSupportedVersion: string;\n  latestVersion: string;\n  updateMode: UpdateMode;\n  storeUrl: string | null;\n  maintenance: { on: boolean; message: string | null };\n  contract: { min: number; max: number; sunset: string | null };\n  flags: Record<string, FlagValue>;\n  message: string | null;\n  locale: string;\n}\n\n/** The parameters of one platform, as the database holds them (the admin edits this shape). */\nexport interface AppConfigRecord {\n  platform: Platform;\n  minSupportedVersion: string;\n  latestVersion: string;\n  updateOverride: UpdateMode | null;\n  storeUrl: string | null;\n  maintenanceOn: boolean;\n  maintenanceMessage: Record<string, string>;\n  message: Record<string, string>;\n  contractMin: number;\n  contractMax: number;\n  contractSunset: string | null;\n  flags: Record<string, FlagValue>;\n  revision: number;\n  updatedAt: string;\n  updatedBy: string;\n}\n\n/** What a client says about itself (headers or query). */\nexport interface ClientInfo {\n  platform?: string | null;\n  version?: string | null;\n  contract?: string | number | null;\n  language?: string | null;\n}\n\nexport type Version = readonly [major: number, minor: number, patch: number];\n\nconst VERSION = /^v?(\\d{1,6})(?:\\.(\\d{1,6}))?(?:\\.(\\d{1,6}))?(?:[-+].*)?$/;\n\n/** `1.4`, `v1.4.0`, `1.4.0-beta.2` and `1.4.0+42` all read as `[1, 4, 0]`; anything else is `null`. */\nexport function parseVersion(text: string | null | undefined): Version | null {\n  const match = VERSION.exec((text ?? \"\").trim());\n  return match ? [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)] : null;\n}\n\nexport function compareVersions(a: Version, b: Version): number {\n  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];\n}\n\nexport function formatVersion(version: Version): string {\n  return version.join(\".\");\n}\n\nconst ZERO: Version = [0, 0, 0];\n\nexport function isPlatform(value: unknown): value is Platform {\n  return typeof value === \"string\" && (PLATFORMS as readonly string[]).includes(value.trim().toLowerCase());\n}\n\nexport function toPlatform(value: string | null | undefined): Platform | null {\n  const wanted = (value ?? \"\").trim().toLowerCase();\n  return isPlatform(wanted) ? wanted : null;\n}\n\n/** The permissive parameters a platform starts with: nobody is locked out. */\nexport function defaultRecord(platform: Platform): AppConfigRecord {\n  return {\n    platform,\n    minSupportedVersion: \"0.0.0\",\n    latestVersion: \"0.0.0\",\n    updateOverride: null,\n    storeUrl: null,\n    maintenanceOn: false,\n    maintenanceMessage: {},\n    message: {},\n    contractMin: 1,\n    contractMax: 1,\n    contractSunset: null,\n    flags: {},\n    revision: 1,\n    updatedAt: new Date(0).toISOString(),\n    updatedBy: \"seed\",\n  };\n}\n\nconst LANGUAGE = /^[a-z]{2}$/;\nconst FLAG_KEY = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;\nconst MAX_TEXT = 500;\n\nfunction checkTexts(field: string, texts: Record<string, string>): string[] {\n  return Object.entries(texts).flatMap(([language, text]) => {\n    if (!LANGUAGE.test(language)) return [`${field} language must be two letters: ${language}`];\n    return text.length > MAX_TEXT ? [`${field}.${language} is too long`] : [];\n  });\n}\n\n/** The safety bounds of an edit; an empty list means the record can be published. */\nexport function validateRecord(record: AppConfigRecord): string[] {\n  const problems: string[] = [];\n  const min = parseVersion(record.minSupportedVersion);\n  const latest = parseVersion(record.latestVersion);\n  if (!min || !latest) problems.push(\"versions must look like 1.4.0\");\n  else if (compareVersions(latest, min) < 0) problems.push(\"latestVersion is older than minSupportedVersion\");\n  if (!Number.isInteger(record.contractMin) || record.contractMin < 1 || record.contractMax < record.contractMin) {\n    problems.push(\"contract range must satisfy 1 <= min <= max\");\n  }\n  if (record.storeUrl !== null && !/^https:\\/\\/[^\\s/]+/.test(record.storeUrl)) problems.push(\"storeUrl must be an absolute https URL\");\n  problems.push(...checkTexts(\"message\", record.message), ...checkTexts(\"maintenanceMessage\", record.maintenanceMessage));\n  for (const [key, value] of Object.entries(record.flags)) {\n    if (!FLAG_KEY.test(key)) problems.push(`flag key not allowed: ${key}`);\n    if (![\"boolean\", \"number\", \"string\"].includes(typeof value)) problems.push(`flag ${key} must be a boolean, number or string`);\n  }\n  return problems;\n}\n\n/** `none`, `soft` or `force` for the version the client runs. The operator's override wins. */\nexport function updateModeFor(record: AppConfigRecord, client: Version | null): UpdateMode {\n  if (record.updateOverride) return record.updateOverride;\n  if (!client) return \"none\";\n  if (compareVersions(client, parseVersion(record.minSupportedVersion) ?? ZERO) < 0) return \"force\";\n  return compareVersions(client, parseVersion(record.latestVersion) ?? ZERO) < 0 ? \"soft\" : \"none\";\n}\n\nfunction pickLanguage(wanted: string | null | undefined, ...texts: Record<string, string>[]): string {\n  const language = (wanted ?? \"en\").toLowerCase();\n  return texts.some((t) => language in t) ? language : \"en\";\n}\n\n/** The public payload for a client, its texts in the best language available. */\nexport function buildPayload(record: AppConfigRecord, client: Version | null, language?: string | null): AppConfigPayload {\n  const chosen = pickLanguage(language, record.message, record.maintenanceMessage);\n  const text = (texts: Record<string, string>) => texts[chosen] ?? texts.en ?? null;\n  return {\n    platform: record.platform,\n    minSupportedVersion: formatVersion(parseVersion(record.minSupportedVersion) ?? ZERO),\n    latestVersion: formatVersion(parseVersion(record.latestVersion) ?? ZERO),\n    updateMode: updateModeFor(record, client),\n    storeUrl: record.storeUrl,\n    maintenance: { on: record.maintenanceOn, message: text(record.maintenanceMessage) },\n    contract: { min: record.contractMin, max: record.contractMax, sunset: record.contractSunset },\n    flags: record.flags,\n    message: text(record.message),\n    locale: chosen,\n  };\n}\n\nexport type GuardCode = \"upgrade-required\" | \"contract-unsupported\";\n\n/** What the 426 filter does with a request. */\nexport type GuardResult = {\n  /** `Deprecation: true` — the contract the client speaks is served but on its way out. */\n  deprecation: boolean;\n  /** The newest contract the backend speaks (`X-Contract-Version` of the answer). */\n  contract: number;\n} & (\n  | {\n      status: 200;\n      /** The `Sunset` HTTP date, when announced. */\n      sunset?: string;\n    }\n  | {\n      status: 426;\n      code: GuardCode;\n      /** The `appConfig` of a 426: the payload with `updateMode: \"force\"`. */\n      payload: AppConfigPayload;\n    }\n);\n\nfunction contractOf(value: string | number | null | undefined): number | null {\n  const n = typeof value === \"number\" ? value : Number.parseInt(String(value ?? \"\").trim(), 10);\n  return Number.isInteger(n) && n >= 1 ? n : null;\n}\n\nfunction sunsetDate(day: string): string {\n  const [y, m, d] = day.split(\"-\").map(Number) as [number, number, number];\n  return new Date(Date.UTC(y, m - 1, d + 1)).toUTCString();\n}\n\n/** The 426 filter's decision: below the minimum or an unserved contract is refused; N-1 is deprecated. */\nexport function evaluateGuard(record: AppConfigRecord, client: ClientInfo): GuardResult {\n  const version = parseVersion(client.version);\n  const contract = contractOf(client.contract);\n  const base = { deprecation: false, contract: record.contractMax };\n  const tooOld = version !== null && compareVersions(version, parseVersion(record.minSupportedVersion) ?? ZERO) < 0;\n  const contractGone = contract !== null && contract < record.contractMin;\n  if (tooOld || contractGone) {\n    const payload: AppConfigPayload = { ...buildPayload(record, version, client.language), updateMode: \"force\" };\n    return { ...base, status: 426, code: tooOld ? \"upgrade-required\" : \"contract-unsupported\", payload };\n  }\n  if (contract !== null && contract < record.contractMax) {\n    return { ...base, status: 200, deprecation: true, ...(record.contractSunset ? { sunset: sunsetDate(record.contractSunset) } : {}) };\n  }\n  return { ...base, status: 200 };\n}\n\nconst SEMVER = /^\\d+\\.\\d+\\.\\d+$/;\n\n/** A structural check of a payload read from the network: anything else is ignored (fail open). */\nexport function isAppConfigPayload(value: unknown): value is AppConfigPayload {\n  if (typeof value !== \"object\" || value === null) return false;\n  const v = value as Record<string, unknown>;\n  const maintenance = v.maintenance as Record<string, unknown> | undefined;\n  const contract = v.contract as Record<string, unknown> | undefined;\n  return (\n    isPlatform(v.platform) &&\n    typeof v.minSupportedVersion === \"string\" &&\n    SEMVER.test(v.minSupportedVersion) &&\n    typeof v.latestVersion === \"string\" &&\n    SEMVER.test(v.latestVersion) &&\n    (UPDATE_MODES as readonly unknown[]).includes(v.updateMode) &&\n    typeof maintenance === \"object\" &&\n    typeof maintenance?.on === \"boolean\" &&\n    typeof contract === \"object\" &&\n    typeof contract?.min === \"number\" &&\n    typeof contract?.max === \"number\"\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/client.d.ts

@@ -0,0 +1,83 @@
+import { AppConfigPayload, Platform } from './index.js';
+
+/** What the app must show, decided from the payload. Maintenance outranks an update. */
+type Decision = {
+    kind: "ok";
+} | {
+    kind: "soft";
+    config: AppConfigPayload;
+} | {
+    kind: "force";
+    config: AppConfigPayload;
+} | {
+    kind: "maintenance";
+    config: AppConfigPayload;
+};
+type AppConfigStatus = "idle" | "loading" | "ready" | "failed";
+interface AppConfigState {
+    status: AppConfigStatus;
+    config: AppConfigPayload | null;
+    decision: Decision;
+    /** The 426 payload that forced the screen, if a request got one. */
+    upgradeRequired: AppConfigPayload | null;
+}
+/** A place to remember which version's soft prompt the person already dismissed. */
+interface DismissStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+}
+interface AppConfigClientOptions {
+    /** The backend's origin, e.g. `https://dev.orazaka.com`. */
+    baseUrl: string;
+    platform: Platform;
+    /** The version the app runs (`1.4.0`), from the build, never typed twice. */
+    version: string;
+    /** The API contract the app speaks. Defaults to 1. */
+    contract?: number;
+    build?: string;
+    fetch?: typeof fetch;
+    /** The language to ask texts in (`fr`); defaults to the backend's `Accept-Language` reading. */
+    language?: () => string | undefined;
+    storage?: DismissStorage;
+    now?: () => number;
+    /** A check requested sooner than this after the last one is skipped (resume storms). Default 300 s. */
+    minIntervalMs?: number;
+}
+/** Maintenance first, then a forced update, then a soft one. */
+declare function decide(config: AppConfigPayload | null, softDismissedFor?: string | null): Decision;
+/** The headers every request of the app carries. */
+declare function clientHeaders(info: {
+    platform: Platform;
+    version: string;
+    contract?: number;
+    build?: string;
+}): Record<string, string>;
+/** Whether a response is the backend telling the app to update. */
+declare function isUpgradeRequired(response: {
+    status: number;
+}): boolean;
+/** The `appConfig` member of an already parsed `426` body, or `null` (for a transport that is not `fetch`, e.g. XHR). */
+declare function upgradePayloadOf(body: unknown): AppConfigPayload | null;
+/** The `appConfig` of a `426` response, or `null` when the body is not one (the app still must update). */
+declare function readUpgradeRequired(response: Response): Promise<AppConfigPayload | null>;
+interface AppConfigClient {
+    /** The headers every request carries — for a transport that is not `fetch` (XHR, a native module). */
+    readonly headers: Readonly<Record<string, string>>;
+    getState(): AppConfigState;
+    subscribe(listener: () => void): () => void;
+    /** Checks the backend. Skipped when a check ran less than `minIntervalMs` ago, unless `force`. Never throws. */
+    check(options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** The person dismissed the soft prompt: not shown again for this `latestVersion`. */
+    dismissSoft(): Promise<void>;
+    /** A request got a 426 (the global interceptor calls this). */
+    reportUpgradeRequired(payload: AppConfigPayload | null): void;
+    /** `fetch` that sends the client headers and reports every 426 to this client. */
+    fetch: typeof fetch;
+    /** Checks again each time `resume` fires (app foreground, tab visible). Returns the unsubscribe. */
+    attach(resume: (callback: () => void) => () => void): () => void;
+}
+declare function createAppConfigClient(options: AppConfigClientOptions): AppConfigClient;
+
+export { type AppConfigClient, type AppConfigClientOptions, type AppConfigState, type AppConfigStatus, type Decision, type DismissStorage, clientHeaders, createAppConfigClient, decide, isUpgradeRequired, readUpgradeRequired, upgradePayloadOf };