@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/signing-in.ts

@@ -0,0 +1,213 @@
+import { MARK } from "./signing-in-mark.js";
+
+/**
+ * The "Signing in" screen (components/15, ADR-032): the platform's mark moving
+ * in the platform's colours, and "Signing in" — no product name, so it suits
+ * every Tenant. The Customer Portal shows it over a flow page that is leaving,
+ * and `continuePage` shows it at the Application's callback, so the hand-over
+ * from the sign-in host to the Application looks like one screen.
+ *
+ * Plain markup and CSS, no inline `style` attribute, so a page with a strict
+ * Content-Security-Policy only has to allow the one `<style>` element.
+ */
+
+/** One swell of the mark, in milliseconds (`SIGNING_IN_CSS`). */
+const CYCLE_MS = 2800;
+const PAD = 50;
+const ID = "signing-in";
+
+/**
+ * Where in its loop the animation starts, as `animation-delay`: the wall
+ * clock's position in the cycle. The portal's screen and the callback's page
+ * both start there, so the mark does not jump back at the hand-over.
+ */
+export function signingInPhase(now = Date.now()): string {
+  return `-${now % CYCLE_MS}ms`;
+}
+
+/**
+ * A circle under each drop of the mark, which swells in turn (`signing-in-*`
+ * keyframes): the gold head gathers, the side drops reach out, the teal head
+ * fills and the teal drop reaches down.
+ */
+const DROPS = [
+  { name: "head", fill: "arch", cx: 514, cy: 110, r: 100 },
+  { name: "drop-left", fill: "arch", cx: 116, cy: 534, r: 100 },
+  { name: "drop-right", fill: "arch", cx: 898, cy: 534, r: 100 },
+  { name: "stem-head", fill: "stem", cx: 512, cy: 420, r: 80 },
+  { name: "stem-drop", fill: "stem", cx: 510, cy: 830, r: 122 },
+] as const;
+
+/**
+ * The traced mark, drawn as supplied, with the swelling circles. A goo filter
+ * (blur, then a hard alpha edge) melts a swollen circle into the outline
+ * around it, as a liquid would. `width` and `height` keep it small should the
+ * stylesheet be refused.
+ */
+function markSvg(): string {
+  const box = [-PAD, -PAD, MARK.width + 2 * PAD, MARK.height + 2 * PAD] as const;
+  const drops = (fill: "arch" | "stem") =>
+    DROPS.filter((d) => d.fill === fill)
+      .map((d) => `<circle class="${ID}-${d.name}" cx="${d.cx}" cy="${d.cy}" r="${d.r}"/>`)
+      .join("");
+  return (
+    `<svg class="${ID}-mark" viewBox="${box.join(" ")}" width="156" height="${Math.round((156 * box[3]) / box[2])}" aria-hidden="true" focusable="false">` +
+    `<defs>` +
+    `<linearGradient id="${ID}-arch" gradientUnits="userSpaceOnUse" x1="140" y1="520" x2="420" y2="230"><stop offset="0.3" class="${ID}-teal"/><stop offset="0.78" class="${ID}-gold"/></linearGradient>` +
+    `<linearGradient id="${ID}-stem" gradientUnits="userSpaceOnUse" x1="0" y1="440" x2="0" y2="970"><stop offset="0.2" class="${ID}-teal"/><stop offset="1" class="${ID}-teal-deep"/></linearGradient>` +
+    `<filter id="${ID}-goo" filterUnits="userSpaceOnUse" x="${box[0]}" y="${box[1]}" width="${box[2]}" height="${box[3]}" color-interpolation-filters="sRGB">` +
+    `<feGaussianBlur in="SourceGraphic" stdDeviation="16"/><feColorMatrix values="1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 20 -9"/><feComposite in="SourceGraphic" operator="over"/>` +
+    `</filter>` +
+    `</defs>` +
+    `<g filter="url(#${ID}-goo)">` +
+    `<g fill="url(#${ID}-arch)"><path d="${MARK.arch}"/>${drops("arch")}</g>` +
+    `<g fill="url(#${ID}-stem)"><path d="${MARK.stem}"/>${drops("stem")}</g>` +
+    `</g>` +
+    `<g class="${ID}-gloss">${MARK.gloss.map((d) => `<path d="${d}"/>`).join("")}</g>` +
+    `</svg>`
+  );
+}
+
+const esc = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+/**
+ * What goes inside the screen's `.signing-in` element: the mark and the label.
+ * With `href` the label is a link there, for a browser that does not follow a
+ * `<meta refresh>`.
+ */
+export function signingInMarkup(opts: { text?: string; href?: string } = {}): string {
+  const text = esc(opts.text ?? "Signing in");
+  const label = opts.href ? `<a href="${esc(opts.href)}">${text}</a>` : text;
+  return `${markSvg()}<p class="${ID}-text">${label}</p>`;
+}
+
+/**
+ * The screen's stylesheet. `.signing-in` is a fixed cover over whatever page
+ * it sits on; `.signing-in.fade` fades it in. Light or dark follows the
+ * system, unless the page's root says `data-theme="light"`.
+ */
+export const SIGNING_IN_CSS = `
+.signing-in {
+  --si-gold: #f2c230;
+  --si-teal: #35a8a4;
+  --si-teal-deep: #2b7f8b;
+  --si-ground: #f4f4f1;
+  --si-glow: 14%;
+  --si-text: color-mix(in srgb, #0a0b0d 72%, var(--si-ground));
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+  display: grid;
+  place-content: center;
+  justify-items: center;
+  gap: 28px;
+  padding: env(safe-area-inset-top, 0px) 24px env(safe-area-inset-bottom, 0px);
+  background:
+    radial-gradient(260px 230px at 50% calc(50% - 20px), color-mix(in srgb, var(--si-gold) var(--si-glow), transparent), transparent),
+    var(--si-ground);
+  color-scheme: light;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) .signing-in {
+    --si-ground: #0a0b0d;
+    --si-glow: 7%;
+    --si-text: #a5aab3;
+    color-scheme: dark;
+  }
+}
+.signing-in.fade {
+  animation: signing-in-fade 0.2s cubic-bezier(0.2, 0.8, 0.2, 1) both;
+}
+@keyframes signing-in-fade {
+  from {
+    opacity: 0;
+  }
+}
+.signing-in-mark {
+  width: 156px;
+  height: auto;
+  overflow: visible;
+}
+@media (min-width: 720px) {
+  .signing-in-mark {
+    width: 176px;
+  }
+}
+.signing-in-gold {
+  stop-color: var(--si-gold);
+}
+.signing-in-teal {
+  stop-color: var(--si-teal);
+}
+.signing-in-teal-deep {
+  stop-color: var(--si-teal-deep);
+}
+.signing-in-gloss {
+  fill: #fff;
+  opacity: 0.5;
+}
+/*
+ * One swell runs through the mark every 2.8 s: each circle grows past its drop
+ * (the goo filter melts it in), overshoots back a little and rests. CSS, not
+ * SMIL: Chromium starts SMIL at the load event, CSS from the first paint.
+ */
+.signing-in-mark circle {
+  transform-box: fill-box;
+  transform-origin: center;
+  /* Longhands: a shorthand here would reset the name each drop sets below. */
+  animation-duration: ${CYCLE_MS}ms;
+  animation-delay: var(--si-phase, 0s);
+  animation-timing-function: cubic-bezier(0.45, 0, 0.55, 1);
+  animation-iteration-count: infinite;
+}
+.signing-in-head { animation-name: signing-in-head; }
+.signing-in-drop-left { animation-name: signing-in-drop-left; }
+.signing-in-drop-right { animation-name: signing-in-drop-right; }
+.signing-in-stem-head { animation-name: signing-in-stem-head; }
+.signing-in-stem-drop { animation-name: signing-in-stem-drop; }
+@keyframes signing-in-head {
+  0%, 2%, 36%, 100% { transform: none; }
+  13% { transform: translate(0, -18px) scale(1.18); }
+  27% { transform: translate(0, 4px) scale(0.98); }
+}
+@keyframes signing-in-drop-left {
+  0%, 16%, 55%, 100% { transform: none; }
+  32% { transform: translate(-34px, 28px) scale(1.08); }
+  46% { transform: translate(6px, -5px) scale(0.99); }
+}
+@keyframes signing-in-drop-right {
+  0%, 16%, 55%, 100% { transform: none; }
+  32% { transform: translate(34px, 28px) scale(1.08); }
+  46% { transform: translate(-6px, -5px) scale(0.99); }
+}
+@keyframes signing-in-stem-head {
+  0%, 34%, 66%, 100% { transform: none; }
+  46% { transform: translate(0, -6px) scale(1.25); }
+  58% { transform: translate(0, 2px) scale(0.975); }
+}
+@keyframes signing-in-stem-drop {
+  0%, 46%, 86%, 100% { transform: none; }
+  62% { transform: translate(0, 38px) scale(1.066); }
+  76% { transform: translate(0, -6px) scale(0.992); }
+}
+/* Held at rest: shortening the durations, as reduced-motion rules often do, would make the loop flicker. */
+@media (prefers-reduced-motion: reduce) {
+  .signing-in-mark circle {
+    animation: none !important;
+  }
+}
+.signing-in-text {
+  margin: 0;
+  /* Letter spacing trails the last letter too: pad the start to keep the word centred. */
+  padding-left: 0.28em;
+  /* The portal's own stack, so the screen is the same on the portal and at a callback. */
+  font: 600 12px/1.5 ui-sans-serif, -apple-system, BlinkMacSystemFont, "SF Pro Text", "Inter", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  letter-spacing: 0.28em;
+  text-transform: uppercase;
+  color: var(--si-text);
+}
+.signing-in-text a {
+  color: inherit;
+  text-decoration: none;
+}
+`;

package/src/tags.ts

@@ -0,0 +1,146 @@
+/**
+ * Tags (ADR-057). A tag marks a subset of Users or Tenants (the platform's
+ * scope) or of one Tenant's Customers (that Tenant's scope). It is derived —
+ * computed from what the Engine already records, never stored — or assigned
+ * by a person or by a rule from a closed list. A tag selects; it never grants.
+ *
+ * Pure and dependency-free: the Operations API stores and evaluates, the Admin
+ * UI and the Tenant's tools read the same vocabulary.
+ */
+
+
+export const TAG_SUBJECTS = ["user", "customer", "tenant"] as const;
+
+export type TagSubject = (typeof TAG_SUBJECTS)[number];
+
+/** Who sees a tag on a subject (§4): staff only, also the subject itself, or (a platform tag on a Tenant) also the Tenant's staff. */
+export const TAG_VISIBILITIES = ["staff", "subject", "tenant"] as const;
+
+export type TagVisibility = (typeof TAG_VISIBILITIES)[number];
+
+/** The Admin UI's tag colours: a tag is told apart at a glance, never by colour alone. */
+export const TAG_COLOURS = ["slate", "gold", "teal", "green", "amber", "red", "violet", "blue"] as const;
+
+export type TagColour = (typeof TAG_COLOURS)[number];
+
+/**
+ * The closed list of rules (§3). A rule assigns when its moment comes and never removes. `on_hard_bounce` and
+ * `on_complaint` (ADR-060 §5): mail to the subject's address bounced for good, or was reported as spam.
+ */
+export type TagRule = { kind: "at_creation" } | { kind: "on_join" } | { kind: "on_tier"; tier: string } | { kind: "on_restore" } | { kind: "on_hard_bounce" } | { kind: "on_complaint" };
+
+export const TAG_RULE_KINDS = ["at_creation", "on_join", "on_tier", "on_restore", "on_hard_bounce", "on_complaint"] as const;
+
+export type TagRuleKind = (typeof TAG_RULE_KINDS)[number];
+
+/**
+ * What carrying a tag does (ADR-060 §4), from a closed list, beside the rules that assign it. An effect never grants:
+ * `no_email` only takes e-mail away. Mail to a subject with such a tag is not sent; in-app Notifications and
+ * tickets still appear. A Customer's mail also stops while its User carries one.
+ */
+export const TAG_EFFECTS = ["no_email"] as const;
+
+export type TagEffect = (typeof TAG_EFFECTS)[number];
+
+/** An assigned tag's name (§2): lowercase letters, digits and `-`, 2 to 40 characters, never `:` or `=`. */
+export const TAG_NAME = /^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$/;
+
+export function tagNameProblem(name: string): string | null {
+  if (TAG_NAME.test(name)) return null;
+  return "2 to 40 lowercase letters, digits or -, starting and ending with a letter or digit";
+}
+
+/** A derived tag is written `<kind>=<value>`; an assigned one never contains `=`. */
+export function isDerivedTag(name: string): boolean {
+  return name.includes("=");
+}
+
+/** A tag as answers carry it on a subject. */
+export interface TagRef {
+  /** The tag's id; absent for a derived tag, which is no record. */
+  id?: string;
+  name: string;
+  derived: boolean;
+  colour?: TagColour;
+  visibility?: TagVisibility;
+}
+
+/** A tag's record, as the Tags page and the Tenant API read it. */
+export interface TagView {
+  id: string;
+  name: string;
+  /** `<slug>:<name>` for a Tenant tag, the bare name for a platform one. */
+  shown: string;
+  scope: "platform" | "tenant";
+  /** The Tenant's ARID, for a Tenant tag. */
+  tenant?: string;
+  subject: TagSubject;
+  visibility: TagVisibility;
+  description: string;
+  colour: TagColour;
+  rules: TagRule[];
+  /** What carrying it does (ADR-060 §4). */
+  effects: TagEffect[];
+  /** Kept by the Engine in every scope: cannot be deleted or renamed, its effects and rules are fixed. */
+  system: boolean;
+  subjects: number;
+  created_at: string;
+  updated_at: string;
+}
+
+/** How a tag reads on a page: `<slug>:<name>` in a Tenant's scope (§1). */
+export function shownTagName(name: string, slug?: string | null): string {
+  return slug ? `${slug}:${name}` : name;
+}
+
+/** A selector (§6): every tag of `all`, at least one of `any`, none of `none`. An empty selector selects everyone. */
+export interface TagSelector {
+  all?: string[];
+  any?: string[];
+  none?: string[];
+}
+
+export function selectorMatches(selector: TagSelector, tags: Iterable<string>): boolean {
+  const has = new Set(tags);
+  if (selector.all?.some((t) => !has.has(t))) return false;
+  if (selector.any?.length && !selector.any.some((t) => has.has(t))) return false;
+  if (selector.none?.some((t) => has.has(t))) return false;
+  return true;
+}
+
+export function selectorTags(selector: TagSelector): string[] {
+  return Array.from(new Set([...(selector.all ?? []), ...(selector.any ?? []), ...(selector.none ?? [])]));
+}
+
+/** Why a selector cannot be used, or null: each entry an assigned name or a derived `<kind>=<value>`, at most 20 in all. */
+export function selectorProblem(selector: unknown): string | null {
+  if (!selector || typeof selector !== "object" || Array.isArray(selector)) return "a selector is { all?, any?, none? }";
+  const s = selector as Record<string, unknown>;
+  for (const k of Object.keys(s)) if (k !== "all" && k !== "any" && k !== "none") return `unknown key ${k}`;
+  let n = 0;
+  for (const k of ["all", "any", "none"] as const) {
+    const v = s[k];
+    if (v === undefined) continue;
+    if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) return `${k} is a list of tag names`;
+    for (const t of v as string[]) {
+      n++;
+      if (isDerivedTag(t) ? !/^[a-z_]+=[a-z0-9_.-]+$/.test(t) : !TAG_NAME.test(t)) return `${t} is not a tag name`;
+    }
+  }
+  return n > 20 ? "at most 20 tags in a selector" : null;
+}
+
+/** A selector as a query parameter (`?tags=`): JSON, so a list filter reads it back whole. */
+export function encodeSelector(selector: TagSelector): string {
+  return JSON.stringify(selector);
+}
+
+export function decodeSelector(raw: string | null | undefined): TagSelector | null {
+  if (!raw) return null;
+  try {
+    const s = JSON.parse(raw) as unknown;
+    return selectorProblem(s) ? null : (s as TagSelector);
+  } catch {
+    return null;
+  }
+}

package/src/tenant-subscription.ts

@@ -0,0 +1,44 @@
+/**
+ * The Tenant's own subscription to the platform (ADR-064 §11), as
+ * `GET /tenant/v0/subscription` answers it: read-only, for the Tenant's server
+ * or its agent. The catalogue and the rules stay with the Engine.
+ */
+
+export interface TenantPlatformFeatures {
+  own_signin: boolean;
+  own_domain: boolean;
+  /** How many people may hold a role in this Tenant. */
+  team_members: number;
+  /** A response time the Admin UI states, and nothing enforces. */
+  support: string;
+}
+
+/** `Tenant.overage`: off unless a Tenant opts in. `cap` limits what it adds to one month's invoice. */
+export interface TenantOverage {
+  enabled: boolean;
+  cap?: { amount: string; currency: string };
+}
+
+/** What `GET /tenant/v0/subscription` answers: the Tenant's own tier and use, read-only. */
+export interface TenantSubscriptionView {
+  /** The `sbs`, for staff and for a Tenant's own routes. */
+  arid: string | null;
+  tier: string | null;
+  label: string | null;
+  state: string | null;
+  frozen: boolean;
+  renews: boolean | null;
+  period_end: string | null;
+  trial_end: string | null;
+  allowance: TenantAllowance | null;
+  used: { active_customers: number; storage: number };
+  overage: TenantOverage | null;
+  closing_at: string | null;
+  features: TenantPlatformFeatures | null;
+}
+
+/** What a Tenant's tier includes before overage (ADR-064 §5). */
+export interface TenantAllowance {
+  active_customers: number;
+  storage: number;
+}