@marinoscar/platform-contract 0.1.0-next.3 → 0.1.0-next.4

package/dist/esm/exports/schemas.js

@@ -0,0 +1,285 @@
+// =============================================================================
+// The exports slice's wire shapes (issue #744, PP-9.2)
+// =============================================================================
+//
+// The request and responses of `/api/exports` (sources, create, list, get),
+// the format-free cell, column and request-field shapes a source declares, and
+// the JSON writer's file envelope (`schemaVersion: 1`). Shared by
+// `@marinoscar/platform-api/exports` (which wraps them as DTOs, so the OpenAPI
+// document is generated from them) and `@marinoscar/platform-web/exports`.
+//
+// Every object schema is exported so an app can `.extend()` it (a source with
+// richer request fields, a client that reads an extra field).
+// =============================================================================
+import { z } from 'zod';
+import { EXPORT_COLUMN_META_MAX_KEYS, EXPORT_COLUMN_META_MAX_LENGTH, EXPORT_COLUMN_TYPES, EXPORT_DATASET_PATTERN, EXPORT_ID_PATTERN, EXPORT_JSON_SCHEMA_VERSION, EXPORT_REQUEST_FIELD_KINDS, EXPORT_SCOPES, EXPORT_STATUSES, } from './constants.js';
+/**
+ * An export's derived status.
+ *
+ * @stability experimental
+ */
+export const exportStatusSchema = z.enum(EXPORT_STATUSES);
+/**
+ * A source's scope.
+ *
+ * @stability experimental
+ */
+export const exportScopeSchema = z.enum(EXPORT_SCOPES);
+/**
+ * A column's value type.
+ *
+ * @stability experimental
+ */
+export const exportColumnTypeSchema = z.enum(EXPORT_COLUMN_TYPES);
+/**
+ * A request field's kind.
+ *
+ * @stability experimental
+ */
+export const exportRequestFieldKindSchema = z.enum(EXPORT_REQUEST_FIELD_KINDS);
+const exportId = z.string().regex(EXPORT_ID_PATTERN);
+const isoDateTime = z.string().datetime({ offset: true });
+// =============================================================================
+// Cells, columns and the JSON file
+// =============================================================================
+/**
+ * One exported value: text, a number, a boolean or `null`. Dates travel as
+ * ISO 8601 strings; binary columns are never exported.
+ *
+ * @stability experimental
+ */
+export const exportCellSchema = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+]);
+/**
+ * A column's writer-specific typing: flat scalars a custom writer reads (a
+ * Parquet logical type, a unit), at most `EXPORT_COLUMN_META_MAX_KEYS` keys.
+ * The built-in writers ignore it and never write it.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export const exportColumnMetaSchema = z
+    .record(z.string().min(1).max(EXPORT_COLUMN_META_MAX_LENGTH), z.union([z.string().max(EXPORT_COLUMN_META_MAX_LENGTH), z.number(), z.boolean()]))
+    .refine((meta) => Object.keys(meta).length <= EXPORT_COLUMN_META_MAX_KEYS, {
+    message: `meta carries at most ${EXPORT_COLUMN_META_MAX_KEYS} keys`,
+});
+/**
+ * One column of a dataset: its key (the CSV header and the JSON key), a human
+ * label (the XLSX header), its value type and, optionally, writer-specific
+ * `meta`.
+ *
+ * @stability experimental
+ */
+export const exportColumnSchema = z.object({
+    /** Machine name: the CSV header and the JSON key. */
+    key: z.string().min(1).max(128),
+    /** Human header: the XLSX header. */
+    label: z.string().min(1).max(256),
+    /** The value type; numbers are never formula-neutralised in a CSV. */
+    type: exportColumnTypeSchema,
+    /** Writer-specific typing (for example a Parquet logical type). The built-in writers ignore it. */
+    meta: exportColumnMetaSchema.optional(),
+});
+/**
+ * One dataset inside the JSON file.
+ *
+ * @stability experimental
+ */
+export const exportJsonDatasetSchema = z.object({
+    /** The human title (an XLSX sheet name). */
+    title: z.string(),
+    /** The columns, in order. */
+    columns: z.array(exportColumnSchema),
+    /** The rows, keyed by column key. */
+    rows: z.array(z.record(z.string(), exportCellSchema)),
+});
+/**
+ * The JSON writer's file, version 1: the contract a reader of a JSON export
+ * validates against. `datasets` is keyed by dataset name, in the order the
+ * source produced them.
+ *
+ * @stability experimental
+ */
+export const exportJsonFileSchema = z
+    .object({
+    /** {@link EXPORT_JSON_SCHEMA_VERSION}. */
+    schemaVersion: z.literal(EXPORT_JSON_SCHEMA_VERSION),
+    /** The source id (`user-data`). */
+    source: exportId,
+    /** When the export was produced. */
+    exportedAt: isoDateTime,
+    /** One entry per dataset. */
+    datasets: z.record(z.string().regex(EXPORT_DATASET_PATTERN), exportJsonDatasetSchema),
+})
+    .strict();
+// =============================================================================
+// GET /exports/sources
+// =============================================================================
+/**
+ * One choice of a `select` request field.
+ *
+ * @stability experimental
+ */
+export const exportRequestFieldOptionSchema = z.object({
+    /** The value sent. */
+    value: z.string(),
+    /** What the dialog shows. */
+    label: z.string(),
+});
+/**
+ * One field of a source's request, as the export dialog draws it. Derived
+ * from the source's request schema unless the source declares its own.
+ *
+ * @stability experimental
+ */
+export const exportRequestFieldSchema = z.object({
+    /** The key in `request`. */
+    key: z.string().min(1).max(64),
+    /** The field's label. */
+    label: z.string().min(1),
+    /** What to draw. */
+    kind: exportRequestFieldKindSchema,
+    /** Whether the request is refused without it. */
+    required: z.boolean(),
+    /** One line under the field. */
+    description: z.string().optional(),
+    /** The choices of a `select`. */
+    options: z.array(exportRequestFieldOptionSchema).optional(),
+    /** The value when the request omits it. */
+    default: z.union([z.string(), z.boolean()]).optional(),
+});
+/**
+ * One output format a source offers.
+ *
+ * @stability experimental
+ */
+export const exportFormatDescriptorSchema = z.object({
+    /** The writer id (`csv`), sent as `format`. */
+    id: exportId,
+    /** What the dialog calls it. */
+    label: z.string(),
+    /** The file extension, without the dot (`zip` for `csv`). */
+    extension: z.string(),
+    /** The file's media type. */
+    mimeType: z.string(),
+});
+/**
+ * One source the caller may use.
+ *
+ * @stability experimental
+ */
+export const exportSourceDescriptorSchema = z.object({
+    /** The source id (`user-data`), sent as `source`. */
+    id: exportId,
+    /** Whose data it exports. */
+    scope: exportScopeSchema,
+    /** What the dialog calls it. */
+    label: z.string(),
+    /** One sentence about what it contains. */
+    description: z.string().optional(),
+    /** The formats it offers, in registry order. */
+    formats: z.array(exportFormatDescriptorSchema),
+    /** The request fields the dialog draws (empty for a source without options). */
+    fields: z.array(exportRequestFieldSchema),
+    /** For an `org` source: whether the caller may export an organization other than the active one. */
+    crossOrg: z.boolean(),
+});
+/**
+ * `GET /exports/sources`.
+ *
+ * @stability experimental
+ */
+export const exportSourcesResponseSchema = z.object({
+    /** The sources, in registry order. */
+    items: z.array(exportSourceDescriptorSchema),
+});
+// =============================================================================
+// POST /exports
+// =============================================================================
+/**
+ * `POST /exports`. `request` is validated by the source's own schema, at the
+ * route and again when the job starts. `orgId` names the organization of an
+ * `org` source (default: the caller's active organization); another
+ * organization needs the source's cross-organization permission.
+ *
+ * @stability experimental
+ */
+export const createExportSchema = z
+    .object({
+    /** The source id. */
+    source: exportId,
+    /** The format (writer) id. */
+    format: exportId,
+    /** The source's request; `{}` when it takes none. */
+    request: z.record(z.string(), z.unknown()).default({}),
+    /** An `org` source's organization; ignored by a `user` source. */
+    orgId: z.string().uuid().optional(),
+})
+    .strict();
+// =============================================================================
+// The export
+// =============================================================================
+/**
+ * A short-lived signed download, present only on `GET /exports/:id` of a
+ * `ready` export. Never logged, never stored.
+ *
+ * @stability experimental
+ */
+export const exportDownloadSchema = z.object({
+    /** A signed GET with `Content-Disposition: attachment`. */
+    url: z.string().url(),
+    /** When the URL stops working. */
+    expiresAt: isoDateTime,
+});
+/**
+ * One export. Its id is the job id: there is no export table.
+ *
+ * @stability experimental
+ */
+export const exportSchema = z.object({
+    /** The export (job) id. */
+    id: z.string().uuid(),
+    /** The source id. */
+    source: exportId,
+    /** The format id. */
+    format: exportId,
+    /** Whose data. */
+    scope: exportScopeSchema,
+    /** The organization of an `org` export, else `null`. */
+    orgId: z.string().uuid().nullable(),
+    /** The derived status. */
+    status: exportStatusSchema,
+    /** When it was requested. */
+    createdAt: isoDateTime,
+    /** When the file was produced, or the job settled. */
+    completedAt: isoDateTime.nullable(),
+    /** When the file is deleted. */
+    expiresAt: isoDateTime.nullable(),
+    /** The download name. */
+    fileName: z.string().nullable(),
+    /** The file's media type. */
+    mimeType: z.string().nullable(),
+    /** The file's size in bytes. */
+    sizeBytes: z.number().int().nonnegative().nullable(),
+    /** Rows per dataset. */
+    rowCounts: z.record(z.string(), z.number().int().nonnegative()).nullable(),
+    /** The fixed failure message of a `failed` export, else `null`. */
+    error: z.string().nullable(),
+    /** The signed download (`GET /exports/:id` of a `ready` export only), else `null`. */
+    download: exportDownloadSchema.nullable(),
+});
+/**
+ * `GET /exports`: the caller's most recent exports, newest first, without
+ * download URLs.
+ *
+ * @stability experimental
+ */
+export const exportListResponseSchema = z.object({
+    /** At most `EXPORT_LIST_LIMIT`. */
+    items: z.array(exportSchema),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/esm/exports/schemas.js.map

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

package/dist/esm/identity/constants.d.ts

@@ -0,0 +1,273 @@
+/**
+ * The CLOSED set of sign-in failure codes.
+ *
+ * A failed Google sign-in always ends as a 302 to
+ * `${appUrl}/auth/callback?error=<code>`, where `<code>` is one of these and
+ * nothing else: never an exception message, never raw JSON. Free text in that
+ * query string let anyone craft a link that rendered attacker-chosen copy on a
+ * trusted origin.
+ *
+ * - `not_allowlisted`: the email is not on the allowlist.
+ * - `account_disabled`: the account exists but is deactivated.
+ * - `access_denied`: the person cancelled or denied consent at the provider.
+ * - `authentication_failed`: token exchange failed, code replayed or expired,
+ *   no email on the profile, or anything unexpected.
+ * - `server_misconfigured`: seed data is missing.
+ * - `no_organization`: multi-org tenancy mode (`TENANCY_MODE=multi`) and the
+ *   user has no active organization membership.
+ *
+ * The single source: the API resolves every failure to one of these, and the
+ * web app keys its copy off this list (so a new code is a type error there
+ * until it has copy).
+ *
+ * @stability stable
+ */
+export declare const AUTH_ERROR_CODES: readonly ["not_allowlisted", "account_disabled", "access_denied", "authentication_failed", "server_misconfigured", "no_organization"];
+/**
+ * One sign-in failure code: a member of {@link AUTH_ERROR_CODES}.
+ *
+ * @stability stable
+ */
+export type AuthErrorCode = (typeof AUTH_ERROR_CODES)[number];
+/**
+ * The code used for every failure that has no more specific one, and the code
+ * a client shows for an unknown, legacy or missing value (never echo the raw
+ * input).
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_AUTH_ERROR_CODE: AuthErrorCode;
+/**
+ * Whether `value` is one of the closed set of sign-in failure codes.
+ *
+ * @param value - anything, typically the `error` query parameter.
+ * @returns `true` when `value` is an {@link AuthErrorCode}.
+ *
+ * @example
+ * ```ts
+ * const code = isAuthErrorCode(raw) ? raw : DEFAULT_AUTH_ERROR_CODE;
+ * ```
+ *
+ * @stability stable
+ */
+export declare function isAuthErrorCode(value: unknown): value is AuthErrorCode;
+/**
+ * The deployment's tenancy modes (`TENANCY_MODE`): one organization everyone
+ * auto-joins (`single`) or one organization per customer (`multi`).
+ *
+ * @stability stable
+ */
+export declare const TENANCY_MODES: readonly ["single", "multi"];
+/**
+ * One tenancy mode: a member of {@link TENANCY_MODES}.
+ *
+ * @stability stable
+ */
+export type TenancyModeValue = (typeof TENANCY_MODES)[number];
+/**
+ * The org roles the platform ships and an organization administrator can hand
+ * out by default, highest first. A built-in list, no longer the set of
+ * assignable roles: an app or package registers more, and the API reports what
+ * a caller may assign at `GET /api/roles?scope=org`. `admin` is a SYSTEM role
+ * and is never assignable on a membership or an invitation.
+ *
+ * @stability stable
+ */
+export declare const BUILTIN_ORG_ROLES: readonly ["org_admin", "contributor", "viewer"];
+/**
+ * The org roles an organization administrator can hand out, on a membership or
+ * an invitation.
+ *
+ * @deprecated Renamed {@link BUILTIN_ORG_ROLES}: the assignable set is open now
+ *   (read it from `GET /api/roles?scope=org`). Kept as an alias for one release.
+ * @stability stable
+ */
+export declare const ASSIGNABLE_ORG_ROLES: readonly ["org_admin", "contributor", "viewer"];
+/**
+ * One built-in org role: a member of {@link BUILTIN_ORG_ROLES}.
+ *
+ * @stability stable
+ */
+export type BuiltinOrgRole = (typeof BUILTIN_ORG_ROLES)[number];
+/**
+ * An org role id on the wire: a built-in one (autocompleted) or any string an
+ * app or package registered. The API checks it against the role registry and
+ * answers 400 (`code: ROLE_NOT_ASSIGNABLE`) for an unknown or
+ * non-assignable role.
+ *
+ * @stability stable
+ */
+export type AssignableOrgRole = BuiltinOrgRole | (string & {});
+/**
+ * The shape of a role id: lower-case letters, digits, `_` and `-`, starting
+ * with a letter, 1 to 64 characters. Every built-in id matches, and so does an
+ * app's `coach`.
+ *
+ * @stability experimental
+ */
+export declare const ROLE_ID_PATTERN: RegExp;
+/**
+ * The two scopes of a role: `system` (held in `user_roles`, operates the
+ * deployment) and `org` (held on a membership, operates one organization).
+ *
+ * @stability experimental
+ */
+export declare const ROLE_SCOPES: readonly ["system", "org"];
+/**
+ * One role scope: a member of {@link ROLE_SCOPES}.
+ *
+ * @stability experimental
+ */
+export type RoleScopeValue = (typeof ROLE_SCOPES)[number];
+/**
+ * The error `code` (and `details.reason`) of the 400 the API answers when a
+ * role is unknown, of the wrong scope, or registered as not assignable.
+ *
+ * @stability experimental
+ */
+export declare const ROLE_NOT_ASSIGNABLE_REASON = "ROLE_NOT_ASSIGNABLE";
+/**
+ * An organization slug: 2 to 63 lower-case letters, digits or hyphens,
+ * starting and ending with a letter or digit.
+ *
+ * @stability stable
+ */
+export declare const ORG_SLUG_PATTERN: RegExp;
+/**
+ * The statuses of a membership: `active` (grants its role) or `suspended`
+ * (listed, grants nothing).
+ *
+ * @stability stable
+ */
+export declare const ORG_MEMBER_STATUSES: readonly ["active", "suspended"];
+/**
+ * One membership status: a member of {@link ORG_MEMBER_STATUSES}.
+ *
+ * @stability stable
+ */
+export type OrgMemberStatus = (typeof ORG_MEMBER_STATUSES)[number];
+/**
+ * The statuses of an organization invitation.
+ *
+ * @stability stable
+ */
+export declare const ORG_INVITE_STATUSES: readonly ["pending", "accepted", "revoked", "expired"];
+/**
+ * One invitation status: a member of {@link ORG_INVITE_STATUSES}.
+ *
+ * @stability stable
+ */
+export type OrgInviteStatus = (typeof ORG_INVITE_STATUSES)[number];
+/**
+ * The units a personal access token's lifetime is expressed in.
+ *
+ * @stability stable
+ */
+export declare const PAT_DURATION_UNITS: readonly ["minutes", "days", "months"];
+/**
+ * One duration unit: a member of {@link PAT_DURATION_UNITS}.
+ *
+ * @stability stable
+ */
+export type PatDurationUnitValue = (typeof PAT_DURATION_UNITS)[number];
+/**
+ * The bounds of a personal access token's `name` (characters, after trimming)
+ * and `durationValue` (in its unit).
+ *
+ * @stability stable
+ */
+export declare const PAT_LIMITS: {
+    /** The longest accepted token name. */
+    readonly nameMaxLength: 100;
+    /** The smallest accepted duration value. */
+    readonly durationMin: 1;
+    /** The largest accepted duration value. */
+    readonly durationMax: 999;
+};
+/**
+ * The credential a device flow mints on the poll after approval: `session`
+ * (an access JWT plus a refresh token; the default) or `pat` (a personal
+ * access token).
+ *
+ * @stability stable
+ */
+export declare const DEVICE_TOKEN_TYPES: readonly ["session", "pat"];
+/**
+ * One device credential type: a member of {@link DEVICE_TOKEN_TYPES}.
+ *
+ * @stability stable
+ */
+export type DeviceTokenTypeValue = (typeof DEVICE_TOKEN_TYPES)[number];
+/**
+ * The human-readable user code of a device flow: `XXXX-XXXX`, upper-case
+ * letters and digits.
+ *
+ * @stability stable
+ */
+export declare const DEVICE_USER_CODE_PATTERN: RegExp;
+/**
+ * The RFC 8628 section 3.5 / RFC 6749 section 5.2 error codes of
+ * `POST /api/auth/device/token`. A client branches on these, never on the
+ * description or the HTTP status.
+ *
+ * @stability stable
+ */
+export declare const DEVICE_TOKEN_ERROR_CODES: readonly ["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_grant", "invalid_request"];
+/**
+ * One device token error code: a member of {@link DEVICE_TOKEN_ERROR_CODES}.
+ *
+ * @stability stable
+ */
+export type DeviceTokenErrorCode = (typeof DEVICE_TOKEN_ERROR_CODES)[number];
+/**
+ * The statuses a listed device session can have. `approved` means approved but
+ * not yet collected by the device; `expired` means the device collected its
+ * credential.
+ *
+ * @stability stable
+ */
+export declare const DEVICE_SESSION_STATUSES: readonly ["pending", "approved", "denied", "expired"];
+/**
+ * One device session status: a member of {@link DEVICE_SESSION_STATUSES}.
+ *
+ * @stability stable
+ */
+export type DeviceSessionStatus = (typeof DEVICE_SESSION_STATUSES)[number];
+/**
+ * The id of a user extension (`registerCurrentUserExtension`,
+ * `registerUserListExtension` of `@marinoscar/platform-api/identity`): the key
+ * of its contribution under `extensions` in `GET /api/auth/me` and in each row
+ * of `GET /api/users`. Lower-case, starting with a letter, 2 to 48 characters.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export declare const USER_EXTENSION_ID_PATTERN: RegExp;
+/**
+ * The bounds the API holds a user extension's contribution to. A contribution
+ * is JSON, nested at most {@link USER_EXTENSION_LIMITS.maxDepth} levels, with no
+ * key that names a secret; one over a byte bound is dropped (and logged), never
+ * truncated. The bounds are part of the contract so a client can rely on the
+ * size of `extensions`.
+ *
+ * - `currentUserBytes`: one extension's JSON in `GET /api/auth/me`.
+ * - `currentUserTotalBytes`: all extensions together in `GET /api/auth/me`.
+ * - `userListBytes`: one extension's JSON for one row of `GET /api/users`.
+ * - `userListTotalBytes`: all extensions together for one row.
+ * - `maxDepth`: the deepest nesting of a contribution (the extension's own object is level 1).
+ *
+ * @stability experimental
+ */
+export declare const USER_EXTENSION_LIMITS: {
+    /** One extension's JSON in `GET /api/auth/me`, in UTF-8 bytes. */
+    readonly currentUserBytes: 4096;
+    /** All extensions together in `GET /api/auth/me`, in UTF-8 bytes. */
+    readonly currentUserTotalBytes: 16384;
+    /** One extension's JSON for one row of `GET /api/users`, in UTF-8 bytes. */
+    readonly userListBytes: 1024;
+    /** All extensions together for one row of `GET /api/users`, in UTF-8 bytes. */
+    readonly userListTotalBytes: 4096;
+    /** The deepest nesting of a contribution; the extension's own object is level 1. */
+    readonly maxDepth: 5;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/esm/identity/constants.d.ts.map

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