@phis/contracts 0.2.0 → 0.4.0

package/dist/media.d.ts

@@ -0,0 +1,272 @@
+/**
+ * How a Media Space names its kind on the wire.
+ *
+ * Only the name is shared. phis stores the kind as a smallint and that number is its own business --
+ * the site UI never sees it, so putting it here would place a storage detail in a contract.
+ *
+ * What made this worth writing down is that the translation between the two was incomplete: phis knew
+ * four kinds and mapped three, falling back to `"site"` for the rest, while the UI declared its own
+ * union of the same three. An Add-on Space therefore reached the administration surface calling itself
+ * a Site Space, in the one view that shows Add-on Spaces at all. With the names here, the map on the
+ * server side is a total function from its own enum onto this one, and a kind that is added and not
+ * mapped stops compiling.
+ */
+export declare const PHI_MEDIA_SPACE_KINDS: readonly ["site", "user", "group", "addon"];
+export type PhiMediaSpaceKind = (typeof PHI_MEDIA_SPACE_KINDS)[number];
+/**
+ * The kinds a Module may declare a need for.
+ *
+ * The Site Space always exists and is governed by the Core Media role matrix, so declaring it could
+ * only repeat what is already true. An Add-on Space belongs to its Add-on and comes with installing
+ * it, rather than being asked for by a Module.
+ */
+export declare const PHI_DECLARABLE_MEDIA_SPACE_KINDS: readonly ["user", "group"];
+export type PhiDeclarableMediaSpaceKind = (typeof PHI_DECLARABLE_MEDIA_SPACE_KINDS)[number];
+export declare function isPhiDeclarableMediaSpaceKind(value: unknown): value is PhiDeclarableMediaSpaceKind;
+/**
+ * The display properties an Asset may carry, as bits of `media_assets.presentation_flags`.
+ *
+ * Shared because the number itself travels: the site UI sends a mask as a list filter and an array of
+ * these values when metadata is saved, and phis both answers the filter with `flags & mask <> 0` and
+ * refuses a value it does not know. Two sides that must agree on a number is what this package is for,
+ * and the copy that lived on each side had already drifted -- phis still carried `Private`, `Archived`
+ * and `Restricted` long after lifecycle and delivery had become columns of their own.
+ *
+ * Display only. Access is `delivery_policy` and `lifecycle_status`, never a bit in here.
+ *
+ * Bits 1 and 2 are free, and before v1 a bit may be given a new meaning rather than kept vacant.
+ */
+export declare const PhiMediaAssetFlags: {
+    /** Offered as a background. What an Asset is for; where it came from is `meta.source`. */
+    readonly Background: number;
+    readonly Featured: number;
+    readonly Locked: number;
+    readonly Mask: number;
+};
+export type PhiMediaAssetFlag = (typeof PhiMediaAssetFlags)[keyof typeof PhiMediaAssetFlags];
+/**
+ * The rest of the Media vocabulary both sides speak.
+ *
+ * Kind names travel as `kind` in the list contract and are stored on the Asset; Folder flags travel in
+ * the Folder payload; a variant key is a number in a delivery URL and the name phis generates the
+ * rendition under. None of it is one side's private business, and all of it stood twice -- once here in
+ * spirit, once in each repository in fact -- until a bit value drifted and showed what that costs.
+ *
+ * The two resolvers come along because a vocabulary without its total function is only half a contract:
+ * a content type must land on the same kind in the browser and on the server, or an upload is filed as
+ * one thing and listed as another.
+ */
+export declare const PhiMediaFolderFlags: {
+    readonly Collapsed: number;
+    readonly Hidden: number;
+    readonly Locked: number;
+};
+export declare const PhiMediaKind: {
+    readonly Image: "image";
+    readonly Video: "video";
+    readonly Audio: "audio";
+    readonly Pdf: "pdf";
+    readonly Markdown: "markdown";
+    readonly Document: "document";
+    readonly Archive: "archive";
+    readonly Font: "font";
+    readonly Binary: "binary";
+    readonly Other: "other";
+};
+export declare const PhiImageAssetVariantKey: {
+    readonly Thumbnail: 0;
+    readonly Preview: 1;
+    readonly Banner: 2;
+    readonly Header: 3;
+    readonly Card: 4;
+    readonly Hero: 5;
+    readonly Avatar: 6;
+    readonly Logo: 7;
+    readonly Landscape: 8;
+    readonly Portrait: 9;
+};
+export declare const PhiImageAssetVariantKeyName: {
+    readonly 0: "thumbnail";
+    readonly 1: "preview";
+    readonly 2: "banner";
+    readonly 3: "header";
+    readonly 4: "card";
+    readonly 5: "hero";
+    readonly 6: "avatar";
+    readonly 7: "logo";
+    readonly 8: "landscape";
+    readonly 9: "portrait";
+};
+export type PhiImageAssetVariantSpec = {
+    width: number;
+    height: number;
+    fit: "cover" | "contain";
+    quality: number;
+    format: "webp";
+};
+export declare function normalizePhiMediaKind(kind: string | null | undefined): "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font" | "binary" | "other";
+export declare function resolvePhiMediaKindFromContentType(contentType: string | null | undefined): "image" | "video" | "audio" | "pdf" | "markdown" | "document" | "archive" | "font" | "binary" | "other";
+export declare function normalizePhiImageAssetVariantKey(key: unknown): 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 9 | 8 | null;
+export declare function resolvePhiImageAssetVariantKeyName(key: number | null | undefined): string | null;
+export declare function resolvePhiImageAssetVariantSpec(key: number | null | undefined): PhiImageAssetVariantSpec | null;
+/**
+ * The two closed vocabularies that decide whether an Asset may be delivered at all.
+ *
+ * The numbers themselves reach the site UI: an Asset's detail payload carries `lifecycleStatus` and
+ * `deliveryPolicy` as they stand in the row, and the UI decides from them whether `next/image` may be
+ * pointed at the original. phis evaluates `delivery_policy` before any physical lookup, so a value that
+ * means one thing on one side and another on the other would be a visibility bug, not a display bug.
+ *
+ * Unlike the Space kind next to them in phis, which stays a storage detail because the wire carries its
+ * name instead of its number.
+ */
+export declare const PhiMediaLifecycleStatus: {
+    readonly Pending: 1;
+    readonly Ready: 2;
+    readonly Archived: 3;
+    readonly Quarantined: 4;
+    readonly Failed: 5;
+};
+export declare const PhiMediaDeliveryPolicy: {
+    readonly Public: 1;
+    readonly Authenticated: 2;
+    readonly User: 3;
+    readonly Group: 4;
+    readonly Internal: 5;
+};
+/**
+ * What a typeface says about its own proportions.
+ *
+ * Shared because the numbers cross: phis reads them out of the uploaded file once and keeps them on the
+ * Asset, and the site UI turns them into the `size-adjust` and `*-override` descriptors of a fallback
+ * `@font-face`. Without that face a browser sets the page in a local substitute and reflows when the
+ * real file lands, which is the one thing a viewer actually sees.
+ *
+ * Everything is in font units on the `unitsPerEm` grid, so a reader divides rather than assumes 1000.
+ */
+export type PhiFontMetrics = {
+    /** The container the numbers were read from. */
+    format: "sfnt" | "woff" | "woff2";
+    familyName: string | null;
+    unitsPerEm: number;
+    ascent: number;
+    descent: number;
+    lineGap: number;
+    capHeight: number | null;
+    xHeight: number | null;
+    /**
+     * How wide running text sets, as an advance width.
+     *
+     * `glyphs` is the frequency-weighted advance of the characters prose is made of. `os2` is the font's
+     * own `xAvgCharWidth`, which averages every glyph in the file and is therefore wrong for a Latin page
+     * in a family that also carries Greek -- the source travels so a reader can tell the two apart.
+     */
+    xWidthAvg: number | null;
+    xWidthAvgSource: "glyphs" | "os2" | null;
+    /**
+     * What the file classifies itself as, and `null` where it classifies itself as nothing.
+     *
+     * Plenty of good fonts leave both PANOSE and the `OS/2` family class empty, so the absence is a fact
+     * about the file rather than a reason to guess: whoever picks the local substitute decides instead.
+     */
+    category: "serif" | "sans-serif" | "monospace" | null;
+    /**
+     * Which unicode cuts the typeface has characters in, read out of its `cmap` at upload.
+     *
+     * Absent on a font uploaded before cuts existed; such a font is delivered whole.
+     */
+    coverage?: PhiFontCoverage | null;
+};
+/**
+ * The cuts a typeface can be delivered in.
+ *
+ * The number stands in a delivery URL, so it is shared; the named cuts follow the unicode ranges Google
+ * Fonts divides its families along, so a face declared here splits where fonts are commonly split.
+ * `Rest` is not a range but everything a typeface has outside all of them -- its own characters, listed
+ * per font in `PhiFontCoverage.restRanges`, so a page never loses a glyph and never fetches a cut for a
+ * character the font does not have.
+ */
+export declare const PhiFontSubsetKey: {
+    readonly Latin: 0;
+    readonly LatinExt: 1;
+    readonly Cyrillic: 2;
+    readonly CyrillicExt: 3;
+    readonly Greek: 4;
+    readonly GreekExt: 5;
+    readonly Vietnamese: 6;
+    readonly Math: 7;
+    readonly Symbols: 8;
+    readonly Rest: 15;
+};
+export type PhiFontSubsetKeyValue = (typeof PhiFontSubsetKey)[keyof typeof PhiFontSubsetKey];
+/** An inclusive codepoint range. */
+export type PhiUnicodeRange = readonly [start: number, end: number];
+/**
+ * Raised whenever the ranges below or the way a cut is produced changes, so every stored cut is made
+ * again rather than served under a rule that no longer describes it.
+ */
+export declare const PHI_FONT_SUBSET_VERSION = 1;
+/** The named cuts, as Google Fonts' CSS2 API states them for a Latin, Cyrillic and Greek family. */
+export declare const PHI_FONT_SUBSET_RANGES: Readonly<Record<Exclude<PhiFontSubsetKeyValue, 15>, readonly PhiUnicodeRange[]>>;
+/** What a typeface has characters in: the named cuts, and its own characters outside all of them. */
+export type PhiFontCoverage = {
+    subsets: PhiFontSubsetKeyValue[];
+    restRanges: PhiUnicodeRange[];
+};
+export declare function isPhiCodepointInRanges(codepoint: number, ranges: readonly PhiUnicodeRange[]): boolean;
+/** A `unicode-range` descriptor value. */
+export declare function formatPhiUnicodeRange(ranges: readonly PhiUnicodeRange[]): string;
+/** The ranges a cut covers for one typeface: the shared list for a named cut, the font's own for `Rest`. */
+export declare function resolvePhiFontSubsetRanges(key: PhiFontSubsetKeyValue, coverage: PhiFontCoverage): readonly PhiUnicodeRange[];
+export declare function isPhiFontSubsetKey(value: unknown): value is PhiFontSubsetKeyValue;
+/**
+ * The cuts to preload for a page in `locale`, `Latin` first, restricted to what the font covers.
+ *
+ * `locale` is a BCP 47 tag; its script subtag overrides the language's usual one, so `sr-Latn` preloads
+ * `LatinExt` where `sr` preloads `Cyrillic`.
+ */
+export declare function resolvePhiFontPreloadSubsetKeys(locale: string | null | undefined, coverage: PhiFontCoverage): PhiFontSubsetKeyValue[];
+/**
+ * How a body above one part is divided, as a rule rather than as a Provider's private arithmetic.
+ *
+ * It lives here because two parties have to agree on it and neither can be told by the other in time. The
+ * Provider needs the part size to sign one request per part; the Client needs it *before* the plan exists,
+ * because a digest can only be signed into a request if it is known when the request is signed -- so the
+ * Client has to hash the same divisions the Provider is about to address. A rule both compute from the
+ * byte size is the only arrangement where that holds without an extra round trip.
+ *
+ * **Frozen once objects exist under it.** A `sha256-composite` value is a digest of part digests, so it
+ * answers "the same bytes divided the same way". Change the division and the same file yields a different
+ * value, which splits duplicate detection into cohorts that can never match across the change. The value
+ * carries the part size for exactly this reason: a changed rule produces non-matches, never false matches.
+ * Changing it is therefore a decision about the whole corpus, not a tuning knob.
+ *
+ * `PHIS_MEDIA_UPLOAD_MAX_PART_COUNT` is well under S3's ten thousand on purpose. Every part is signed up
+ * front, so the count is also the size of the plan a Client receives and Core holds in memory.
+ */
+export declare const PHIS_MEDIA_UPLOAD_PART_SIZE_BYTES: number;
+export declare const PHIS_MEDIA_UPLOAD_MAX_PART_COUNT = 1000;
+/**
+ * The part size for one body, and the same answer wherever it is asked.
+ *
+ * Sixteen mebibytes until that would need more parts than are allowed, and from there the smallest whole
+ * mebibyte that fits the body into the allowance. Whole mebibytes keep the number short where it is
+ * recorded and keep the arithmetic exact in a browser, where sizes are doubles.
+ */
+export declare function resolvePhiMediaUploadPartSizeBytes(sizeBytes: number): number;
+/** How many parts one body is divided into under `resolvePhiMediaUploadPartSizeBytes`. */
+export declare function resolvePhiMediaUploadPartCount(sizeBytes: number): number;
+/**
+ * The recorded form of a `sha256-composite` digest: the digest, the part count, the part size.
+ *
+ * Duplicate detection compares these values as strings, so everything that decides whether two of them
+ * mean the same thing has to be inside the string. The digest alone would not: the same bytes divided
+ * differently hash differently, and a value that did not say how it was divided would look like a plain
+ * SHA-256 that simply failed to match. Naming the division makes a mismatch legible instead of puzzling.
+ */
+export declare function formatPhiMediaCompositeChecksum(digestHex: string, partCount: number, partSizeBytes: number): string;
+export declare function parsePhiMediaCompositeChecksum(value: string): {
+    digest: string;
+    partCount: number;
+    partSizeBytes: number;
+} | null;