@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/dist/tickets.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Tickets and announcements (ADR-058). A Ticket (`tkt`) is a conversation
+ * with a status between a Customer and its Tenant, a Tenant and the platform,
+ * or a User and the platform on the account page. An announcement is a ticket
+ * of its own primary type: one-to-many, to an audience of tags, with a
+ * lifecycle of its own. Pure and dependency-free: the Operations API decides,
+ * every surface reads the same words.
+ */
+import type { TagSelector } from "./tags.js";
+export declare const PRIMARY_TYPES: readonly ["issue", "request", "feedback", "announcement"];
+export type PrimaryType = (typeof PRIMARY_TYPES)[number];
+/** Who opened it and who answers (§2). Announcements go one way, to an audience. */
+export declare const DIRECTIONS: readonly ["customer_tenant", "tenant_customer", "tenant_platform", "platform_tenant", "user_platform", "platform_user", "tenant_customers", "platform_tenants", "platform_users"];
+export type Direction = (typeof DIRECTIONS)[number];
+export declare const TICKET_STATUSES: readonly ["new", "acknowledged", "in_progress", "waiting", "on_hold", "resolved", "canceled"];
+export type TicketStatus = (typeof TICKET_STATUSES)[number];
+export declare const ANNOUNCEMENT_STATUSES: readonly ["draft", "scheduled", "published", "expired", "withdrawn"];
+export type AnnouncementStatus = (typeof ANNOUNCEMENT_STATUSES)[number];
+export type AnyStatus = TicketStatus | AnnouncementStatus;
+export declare const PRIORITIES: readonly ["low", "normal", "high", "urgent"];
+export type Priority = (typeof PRIORITIES)[number];
+export type Side = "requester" | "handling";
+export declare function statusesOf(primary: PrimaryType): readonly AnyStatus[];
+/** Where a ticket may go from here, for the handling side; the requester may only cancel, resolve or reopen its own. */
+export declare function nextStatuses(primary: PrimaryType, from: TicketStatus, who: Side): TicketStatus[];
+/** A resolved ticket reopens within this many days; later, or canceled, a new ticket links the old one (§4). */
+export declare const REOPEN_DAYS = 14;
+/** The Operator archives a closed ticket this many days after it closed (§4). */
+export declare const ARCHIVE_DAYS = 30;
+/** The words every surface shows for a status and a priority. */
+export declare const STATUS_LABELS: Record<AnyStatus, string>;
+export declare const PRIORITY_LABELS: Record<Priority, string>;
+/** A Tenant's own type of ticket for its Customers (§3): a permanent key, the name a Customer reads, its primary type, the role that answers. */
+export interface TenantTicketType {
+    key: string;
+    name: string;
+    primary: "issue" | "request" | "feedback";
+    handled_by: string;
+}
+/** Open: still work for someone. Closed tickets count toward nobody's open limit. */
+export declare function isOpenStatus(s: AnyStatus): boolean;
+export declare const TENANT_PLATFORM_TYPES: readonly ["engine_defect", "engine_limitation", "engine_question", "changeset", "billing", "onboarding", "security", "notice", "other"];
+/** A party (§5): a person, a role binding, the Tenant's servers. */
+export interface PartyView {
+    /** `customer:<cst>`, `user:<usr>`, `role:<group>` or `tenant:<tnt>`. */
+    ref: string;
+    kind: "person" | "role" | "tenant";
+    side: Side;
+    access: "ro" | "rw";
+    place: "requester" | "assignee" | "watcher";
+    /** How the reader sees it: a name for someone of their own side, "<Tenant> · Support" or "Asturiu · Support" for the other (§7). */
+    label: string;
+}
+/** A post as a reader sees it (§6, §7). */
+export interface PostView {
+    id: string;
+    at: string;
+    side: Side;
+    visibility: "all" | "side";
+    author: {
+        label: string;
+        mine: boolean;
+    };
+    body: string;
+    refs: string[];
+}
+export interface TicketLink {
+    ticket: string;
+    relation: "escalated_from" | "escalated_to" | "duplicate_of" | "relates_to";
+}
+/** A ticket in a list. */
+export interface TicketSummary {
+    arid: string;
+    scope: "platform" | "tenant";
+    tenant?: string;
+    direction: Direction;
+    primary: PrimaryType;
+    secondary: string | null;
+    /** The type's name, as the reader reads it. */
+    type_label: string;
+    subject: string;
+    status: AnyStatus;
+    priority: Priority;
+    archived: boolean;
+    created_at: string;
+    updated_at: string;
+    /** Which side the reader is on, or `audience` when they read it as one of many. */
+    side: Side | "audience";
+    unread: boolean;
+    /** Who it is with, from the reader's side: "<Tenant> · Support", a Customer's name, "Asturiu". */
+    with_label: string;
+}
+/** One ticket, whole, as a reader may see it. */
+export interface TicketView extends TicketSummary {
+    parties: PartyView[];
+    posts: PostView[];
+    links: TicketLink[];
+    refs: string[];
+    audience: TagSelector | null;
+    hold_until: string | null;
+    closed_at: string | null;
+    /** What the reader may do now. */
+    can: {
+        post: boolean;
+        note: boolean;
+        triage: boolean;
+        statuses: TicketStatus[];
+        reopen: boolean;
+    };
+    /** Announcements: languages and the rest; absent for a ticket. */
+    announcement?: AnnouncementFields;
+    /** Changesets and feedback (ADR-059): what the ticket is about beyond its text. */
+    changeset?: {
+        number: number;
+        title: string;
+        date: string;
+        deadline: string | null;
+        url: string | null;
+        applied_version: string | null;
+        reason: string | null;
+    };
+    feedback?: {
+        area: string | null;
+    };
+}
+export interface AnnouncementFields {
+    languages: Record<string, {
+        subject: string;
+        body: string;
+    }>;
+    default_language: string;
+    publish_at: string | null;
+    expires_at: string | null;
+    pinned: boolean;
+    severity: "info" | "warning";
+    replies: boolean;
+}
+/** An announcement in a reader's inbox, in the reader's language or the default. */
+export interface AnnouncementItem {
+    arid: string;
+    subject: string;
+    body: string;
+    published_at: string;
+    expires_at: string | null;
+    pinned: boolean;
+    severity: "info" | "warning";
+    replies: boolean;
+    read: boolean;
+    /** Who it is from: the Tenant's name, or the platform's. */
+    from: string;
+}
+//# sourceMappingURL=tickets.d.ts.map

package/dist/tickets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.d.ts","sourceRoot":"","sources":["../src/tickets.ts"],"names":[],"mappings":"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"}

package/dist/tickets.js

@@ -0,0 +1,65 @@
+/**
+ * Tickets and announcements (ADR-058). A Ticket (`tkt`) is a conversation
+ * with a status between a Customer and its Tenant, a Tenant and the platform,
+ * or a User and the platform on the account page. An announcement is a ticket
+ * of its own primary type: one-to-many, to an audience of tags, with a
+ * lifecycle of its own. Pure and dependency-free: the Operations API decides,
+ * every surface reads the same words.
+ */
+export const PRIMARY_TYPES = ["issue", "request", "feedback", "announcement"];
+/** Who opened it and who answers (§2). Announcements go one way, to an audience. */
+export const DIRECTIONS = ["customer_tenant", "tenant_customer", "tenant_platform", "platform_tenant", "user_platform", "platform_user", "tenant_customers", "platform_tenants", "platform_users"];
+export const TICKET_STATUSES = ["new", "acknowledged", "in_progress", "waiting", "on_hold", "resolved", "canceled"];
+export const ANNOUNCEMENT_STATUSES = ["draft", "scheduled", "published", "expired", "withdrawn"];
+export const PRIORITIES = ["low", "normal", "high", "urgent"];
+/** The moves a ticket's status makes (§4, the state diagram). A requester's reply to `waiting` and a reopen are moves too. */
+const MOVES = {
+    new: ["acknowledged", "in_progress", "canceled"],
+    acknowledged: ["in_progress", "resolved", "canceled"],
+    in_progress: ["waiting", "on_hold", "resolved", "canceled"],
+    waiting: ["in_progress", "canceled"],
+    on_hold: ["in_progress", "canceled"],
+    resolved: ["in_progress"],
+    canceled: [],
+};
+/** Feedback keeps a subset (§4): it is seen, answered and closed, never worked on. */
+const FEEDBACK_STATUSES = ["new", "acknowledged", "resolved", "canceled"];
+export function statusesOf(primary) {
+    if (primary === "announcement")
+        return ANNOUNCEMENT_STATUSES;
+    return primary === "feedback" ? FEEDBACK_STATUSES : TICKET_STATUSES;
+}
+/** Where a ticket may go from here, for the handling side; the requester may only cancel, resolve or reopen its own. */
+export function nextStatuses(primary, from, who) {
+    const allowed = statusesOf(primary);
+    const moves = MOVES[from].filter((s) => allowed.includes(s));
+    if (who === "handling")
+        return moves.filter((s) => s !== "in_progress" || from !== "resolved");
+    return moves.filter((s) => s === "canceled" || s === "resolved" || (from === "resolved" && s === "in_progress"));
+}
+/** A resolved ticket reopens within this many days; later, or canceled, a new ticket links the old one (§4). */
+export const REOPEN_DAYS = 14;
+/** The Operator archives a closed ticket this many days after it closed (§4). */
+export const ARCHIVE_DAYS = 30;
+/** The words every surface shows for a status and a priority. */
+export const STATUS_LABELS = {
+    new: "New",
+    acknowledged: "Seen",
+    in_progress: "In progress",
+    waiting: "Waiting for you",
+    on_hold: "On hold",
+    resolved: "Resolved",
+    canceled: "Canceled",
+    draft: "Draft",
+    scheduled: "Scheduled",
+    published: "Published",
+    expired: "Expired",
+    withdrawn: "Withdrawn",
+};
+export const PRIORITY_LABELS = { low: "Low", normal: "Normal", high: "High", urgent: "Urgent" };
+/** Open: still work for someone. Closed tickets count toward nobody's open limit. */
+export function isOpenStatus(s) {
+    return s !== "resolved" && s !== "canceled" && s !== "draft" && s !== "expired" && s !== "withdrawn";
+}
+export const TENANT_PLATFORM_TYPES = ["engine_defect", "engine_limitation", "engine_question", "changeset", "billing", "onboarding", "security", "notice", "other"];
+//# sourceMappingURL=tickets.js.map

package/dist/tickets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.js","sourceRoot":"","sources":["../src/tickets.ts"],"names":[],"mappings":"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"}

package/dist/tiers.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Tiers (ADR-061). A tier is a named set of features. Engine features come
+ * from the closed catalogue below and the Engine enforces them; Tenant
+ * features are the Tenant's own, and the Engine stores and returns them
+ * without reading them. Dependency-free, so the Admin UI, the Customer Portal
+ * and a Tenant's application draw from the same list the Interface API
+ * enforces.
+ */
+export declare const TIER_LIMITS: {
+    readonly tiers: 32;
+    readonly label: 120;
+    /** Tenant features on one tier. */
+    readonly tenantFeatures: 64;
+    readonly tenantFeatureString: 200;
+    readonly graceDays: 365;
+    /** A file removal gives a person time to act (§6). */
+    readonly storageGraceDaysMin: 30;
+};
+export declare const TIER_KEY_PATTERN: RegExp;
+export declare const TENANT_FEATURE_KEY_PATTERN: RegExp;
+/** `false` or `0`: off. `true`: on, no limit. A positive number: on, up to that number (§2). */
+export type FeatureValue = boolean | number;
+export type EngineFeatureKind = "toggle" | "stock" | "monthly" | "window" | "size";
+export interface EngineFeature {
+    key: string;
+    kind: EngineFeatureKind;
+    /** What a number counts; `null` for a toggle. */
+    unit: "count" | "bytes" | "days" | "people" | null;
+    /** What a tier that does not name it gets. These keep the behaviour from before tiers. */
+    default: FeatureValue;
+    /** What a limit is counted over. */
+    scope: "vault" | "customer" | "wallet" | "upload" | null;
+    /** On a group plan the number is a total for the group (ADR-063 §6). */
+    pooled: boolean;
+    /** The highest number a tier may set; absent: no ceiling here. */
+    max?: number;
+    label: string;
+}
+/** ADR-061 §4. A feature joins this list when the Engine can enforce it. */
+export declare const ENGINE_FEATURES: readonly EngineFeature[];
+export declare function engineFeature(key: string): EngineFeature | undefined;
+export type TenantFeatureValue = boolean | number | string;
+export interface TierDefinition {
+    label?: string;
+    /** Wallet type keys (ADR-029) or `"*"`. A key not in the Definition set is skipped when read. */
+    wallet_types: string[];
+    engine_features?: Record<string, FeatureValue>;
+    tenant_features?: Record<string, TenantFeatureValue>;
+}
+export type Tiers = Record<string, TierDefinition>;
+export declare const TRIGGER_RULE_MODES: readonly ["freeze", "pause"];
+export type TriggerRuleMode = (typeof TRIGGER_RULE_MODES)[number];
+export declare const STORAGE_RULE_MODES: readonly ["keep", "remove"];
+export type StorageRuleMode = (typeof STORAGE_RULE_MODES)[number];
+/** What happens to what a Customer has above a lower tier (ADR-061 §6). */
+export interface TierRules {
+    triggers: {
+        mode: TriggerRuleMode;
+        grace_days: number;
+    };
+    storage: {
+        mode: StorageRuleMode;
+        grace_days: number;
+    };
+    /** When a Tenant last lowered a limit these rules act on; set by the Operations API. */
+    changed_at?: string;
+}
+export interface TenantTierSet {
+    tiers: Tiers;
+    default_tier: string;
+    tier_rules: TierRules;
+}
+export declare function defaultTierRules(): TierRules;
+/** What a Tenant record with no tiers reads as (§3): one tier that creates from every Wallet type. */
+export declare function defaultTierSet(): TenantTierSet;
+/** The fields tiers replace, as records written before ADR-061 keep them. */
+export interface LegacyTierFields {
+    scoping?: unknown;
+    customization?: unknown;
+    passes?: unknown;
+    billing?: unknown;
+    definitions?: unknown;
+}
+/**
+ * Tiers from the four fields they replace (§11). Each default is the one the
+ * old field had, so nothing changes for a Customer. ARIDs in `scoping` become
+ * Wallet type keys through the Tenant's Definition map; one the map does not
+ * know stays an ARID, which `walletTypeArids` still honours.
+ */
+export declare function tiersFromLegacy(raw: LegacyTierFields): TenantTierSet;
+/** A Tenant's tiers, from `tiers` when the record has them, otherwise from the fields they replace. */
+export declare function tierSetOf(raw: LegacyTierFields & {
+    tiers?: unknown;
+    default_tier?: unknown;
+    tier_rules?: unknown;
+}): TenantTierSet;
+/** The tier in force: the stored key, or `default_tier` when there is none or it no longer exists (§3). */
+export declare function tierKeyOf(set: TenantTierSet, stored: string | null | undefined): string;
+export declare function tierOf(set: TenantTierSet, stored: string | null | undefined): TierDefinition;
+/** A feature's value on a tier: as written, or the catalogue's default. */
+export declare function featureValue(tier: TierDefinition, key: string): FeatureValue;
+/** `null`: no limit. `0`: off. Otherwise the number (§2). */
+export declare function featureLimit(value: FeatureValue): number | null;
+/** Whether a Customer may use a feature at all. */
+export declare function featureIsOn(value: FeatureValue): boolean;
+/** The Wallet type ARIDs a tier may create from. `map` is the Tenant's Definition map; a key not in it is skipped (§3). */
+export declare function walletTypeArids(tier: TierDefinition, map: Record<string, string>, all: readonly string[]): Set<string>;
+/** Whether any tier switches a Wallet overlay feature on: the Tenant has customisation at all (ADR-028). */
+export declare function overlaysOn(set: TenantTierSet): boolean;
+/** What a tier may add to a Wallet overlay, in the shape the overlay code checks against. */
+export declare function overlayLimitsOf(tier: TierDefinition): {
+    rename: boolean;
+    arrange: boolean;
+    extra_fields: number;
+    secret_fields: boolean;
+    searchable_fields: number;
+};
+export interface TierProblem {
+    path: (string | number)[];
+    message: string;
+}
+/** Strict checks on a block being written (§3). One entry per problem, with its path. */
+export declare function tierProblems(raw: {
+    tiers?: unknown;
+    default_tier?: unknown;
+    tier_rules?: unknown;
+}): TierProblem[];
+/** Features whose value falls between two tier sets, on tiers that exist in both: what the Admin UI warns about (§12), and what starts a grace period (§6). */
+export declare function loweredFeatures(before: Tiers, after: Tiers): {
+    tier: string;
+    feature: string;
+    from: FeatureValue;
+    to: FeatureValue;
+}[];
+/** One Engine feature as a Customer has it (§9). */
+export interface EntitledFeature {
+    value: FeatureValue;
+    /** Present for stock and monthly limits. On a group plan, the group's total. */
+    used?: number;
+    /** On a group plan, the caller's share. */
+    own?: number;
+}
+/** `GET /v0/customer/entitlements`, and the Tenant API's read of one Customer (§9). */
+export interface CustomerEntitlements {
+    tier: string;
+    label: string;
+    /** Wallet type keys or `"*"`. */
+    wallet_types: string[];
+    engine_features: Record<string, EntitledFeature>;
+    tenant_features: Record<string, TenantFeatureValue>;
+    /** While files are due to be removed (§6). */
+    storage_review?: {
+        at: string;
+        over_bytes: number;
+    };
+}
+export declare function entitlementsOf(set: TenantTierSet, stored: string | null | undefined, used?: Record<string, {
+    used?: number;
+    own?: number;
+}>): CustomerEntitlements;
+/** A feature read for showing: whether it is on, its limit, what is used and what is left. */
+export declare function featureOf(entitlements: CustomerEntitlements, key: string): {
+    on: boolean;
+    limit: number | null;
+    used: number | null;
+    left: number | null;
+};
+//# sourceMappingURL=tiers.d.ts.map

package/dist/tiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../src/tiers.ts"],"names":[],"mappings":"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"}