@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/urlid.ts

@@ -0,0 +1,77 @@
+/**
+ * The ARID type tokens (ADR-008). The Engine's `arid` module keeps the same
+ * list; a test there fails when they differ.
+ */
+export const ARID_TYPE_TOKENS = ["tnt", "usr", "cst", "vlt", "prn", "grp", "pfl", "wlt", "ent", "fld", "att", "wdf", "edf", "fdf", "grt", "trg", "evt", "ntf", "rcv", "trf", "cnt", "msg", "ovl", "pss", "tkt", "sbs"] as const;
+/** The type token a route fixes (ADR-008). */
+export type ResourceType = (typeof ARID_TYPE_TOKENS)[number];
+
+/**
+ * The URL spelling of an ARID (components/02 §Resource URLs).
+ *
+ * A browser URL names a resource by its `ResourceID` alone when the Issuer is
+ * `global`, and by `<issuer>~<ResourceID>` otherwise:
+ *
+ *   /wallets/01M25QTXZNCXBE3DCYZQWAMB72            ARID:0:global:wlt:01M25Q…
+ *   /wallets/device-a~01M25QTXZNCXBE3DCYZQWAMB72   ARID:0:device-a:wlt:01M25Q…
+ *
+ * This is a *rendering* of the ARID, never an identifier of its own: the route
+ * fixes the type, the form fixes the ARID version, and the page rebuilds the
+ * full ARID before anything else sees it. Four rules keep that safe:
+ *
+ *  1. One route family per resource type. A route that could show two types
+ *     cannot rebuild the ARID.
+ *  2. URL forms are added, never retired. A later ARID version gets its own
+ *     form; every form ever linked keeps resolving.
+ *  3. Only a browser URL ever carries this form. Nothing stores, logs, HMACs or
+ *     emits it — those carry the ARID. No Engine component imports this file,
+ *     with one exception (ADR-048): a link to a frontend page that the Engine
+ *     sends to a person — today only the Operations API's approval link of a
+ *     waiting Definition plan. A new case needs an ADR.
+ *  4. A route that moves keeps a redirect from the old path.
+ *
+ * `~` is an RFC 3986 unreserved character that neither the Issuer grammar
+ * (`[a-z0-9-]`) nor a ULID (uppercase Crockford base32) contains, so the form
+ * needs no percent-encoding and parses without lookahead. The grammar is
+ * repeated here rather than imported: the Frontend kit must stay free of
+ * `node:` imports (ADR-013), and `../arid.js` pulls in `node:crypto`.
+ */
+
+/** The Issuer a bare `ResourceID` stands for. Fixed, not per deployment: a link must mean the same thing everywhere. */
+export const URL_DEFAULT_ISSUER = "global";
+const URL_ISSUER_SEPARATOR = "~";
+const ARID_VERSION = "0";
+const ISSUER_REGEX = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const ULID_REGEX = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+const TYPE_REGEX = /^[a-z]{3}$/;
+
+/** The URL segment for an ARID. Throws on a malformed ARID: only a value the Engine issued belongs in a link. */
+export function aridToUrlId(arid: string): string {
+  const parts = arid.split(":");
+  if (parts.length !== 5 || parts[0] !== "ARID" || parts[1] !== ARID_VERSION) throw new Error("malformed ARID");
+  const [, , issuer, , id] = parts;
+  if (!ISSUER_REGEX.test(issuer) || !ULID_REGEX.test(id)) throw new Error("malformed ARID");
+  return issuer === URL_DEFAULT_ISSUER ? id : `${issuer}${URL_ISSUER_SEPARATOR}${id}`;
+}
+
+/**
+ * The ARID a route segment names, for the type the route fixes. Accepts the
+ * canonical form, a lower-cased `ResourceID` (Crockford base32 is
+ * case-insensitive) and a full ARID of the same type; `null` for anything
+ * else. Compare the segment with `aridToUrlId(result)` to decide whether to
+ * redirect to the canonical spelling.
+ */
+export function aridFromUrlId(type: ResourceType, segment: string): string | null {
+  if (!TYPE_REGEX.test(type)) return null;
+  if (segment.startsWith("ARID:")) {
+    const parts = segment.split(":");
+    if (parts.length !== 5 || parts[1] !== ARID_VERSION || parts[3] !== type) return null;
+    if (!ISSUER_REGEX.test(parts[2]) || !ULID_REGEX.test(parts[4])) return null;
+    return segment;
+  }
+  const at = segment.indexOf(URL_ISSUER_SEPARATOR);
+  const issuer = at < 0 ? URL_DEFAULT_ISSUER : segment.slice(0, at);
+  const id = (at < 0 ? segment : segment.slice(at + 1)).toUpperCase();
+  if (!ISSUER_REGEX.test(issuer) || !ULID_REGEX.test(id)) return null;
+  return `ARID:${ARID_VERSION}:${issuer}:${type}:${id}`;
+}

package/src/version.ts

@@ -0,0 +1,15 @@
+/**
+ * The SDK's own version (ADR-074 §4): a semantic version of its own, separate
+ * from the Engine's. A test checks it against `package.json`. The Asturiu
+ * generation is in the name, never in the number.
+ */
+export const SDK_NAME = "@asturiu/v0-sdk";
+export const SDK_VERSION = "1.0.0";
+
+/**
+ * What every Tenant API call sends as its `User-Agent`. The Tenant API
+ * forwards the version as `X-Asturiu-Sdk-Version`, and the Engine records it
+ * on the key as `last_sdk_version`: how an administrator sees what a
+ * Tenant's server runs.
+ */
+export const SDK_USER_AGENT = `asturiu-v0-sdk/${SDK_VERSION}`;

package/templates/asturiu/branding.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "The look of your Customer Portal (ADR-033, ADR-038). Sent whole: a key left out is cleared. An image may be named file:<path>, relative to this file. Take the stored state in first with `asturiu-v0-tenant pull`.",
+  "theme": { "preset": "porcelain" }
+}

package/templates/asturiu/definitions.json

@@ -0,0 +1,23 @@
+{
+  "$comment": "The Definition set: what your Customers keep, as Wallet types with the Entry types they own, and Entry types with their fields (ADR-029, ADR-031). Keys are permanent; labels are what people see. Make it your own, then check it with `asturiu-v0-tenant definitions`.",
+  "shared_fields": {
+    "title": { "label": "Title", "value_type": "text", "searchable": true },
+    "notes": { "label": "Notes", "value_type": "text" }
+  },
+  "wallets": {
+    "documents": {
+      "label": "Documents",
+      "entries": {
+        "document": {
+          "label": "Document",
+          "fields": {
+            "title": { "use": "title", "required": true, "order": 0 },
+            "issued_on": { "label": "Issued on", "value_type": "date", "order": 1 },
+            "file": { "label": "File", "value_type": "attachment", "order": 2 },
+            "notes": { "use": "notes", "order": 3 }
+          }
+        }
+      }
+    }
+  }
+}

package/templates/asturiu/portal.json

@@ -0,0 +1,16 @@
+{
+  "$comment": "What your Customer Portal shows (ADR-037, ADR-039). A switch left out is on; a page left out is back to its default. Redirects stay with an administrator.",
+  "account_link": true,
+  "open_app": true,
+  "back_link": true,
+  "language_menu": true,
+  "appearance": true,
+  "pages": {
+    "profile": { "mode": "portal" },
+    "security": { "mode": "portal" },
+    "plan": { "mode": "portal" },
+    "privacy": { "mode": "portal" },
+    "recovery": { "mode": "portal" },
+    "support": { "mode": "portal" }
+  }
+}