@phis/contracts 0.2.0 → 0.4.0

package/dist/addon.d.ts

@@ -11,35 +11,65 @@
  * no node builtins -- the Add-on states, and Core checks. If something here ever does more than hand
  * back a constant, it is in the wrong package.
  */
-import type { PhiServerAddonCapabilities, PhiServerAddonJobHandler, PhiServerSiteAccess } from "./capabilities.js";
-import type { PhiServerCoreCapabilityId, PhiServerServiceKind } from "./core.js";
-import type { PhiServerAddonQueryCatalog } from "./queries.js";
-import type { PhiServerAddonSchemaDescriptor } from "./schema.js";
-export declare const PHI_SERVER_ADDON_MANIFEST_VERSION: 1;
-export declare const PHI_SERVER_ADDON_ABI_VERSION: 1;
-export type PhiServerAddonAuthPolicy = "internal" | "site-user" | "site-admin" | "operator";
-export type PhiServerAddonHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
-export type PhiServerAddonApiRouteDescriptor = {
+import type { PhisAddonCapabilities, PhisAddonEventHandler, PhisAddonJobHandler, PhisSiteAccess } from "./capabilities.js";
+import type { PhisAddonEventId, PhisCoreCapabilityId, PhisServiceKind } from "./core.js";
+import type { PhisAddonQueryCatalog } from "./queries.js";
+import type { PhisAddonSchemaDescriptor } from "./schema.js";
+export declare const PHIS_ADDON_MANIFEST_VERSION: 1;
+export declare const PHIS_ADDON_ABI_VERSION: 1;
+export type PhisAddonAuthPolicy = "internal" | "site-user" | "site-admin" | "operator";
+export type PhisAddonHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+export type PhisAddonApiRouteDescriptor = {
     id: string;
-    method: PhiServerAddonHttpMethod;
+    method: PhisAddonHttpMethod;
     path: string;
     handler: string;
-    auth: PhiServerAddonAuthPolicy;
+    auth: PhisAddonAuthPolicy;
     siteScoped: boolean;
     bodyLimitBytes?: number;
     rateLimitClass?: string;
     timeoutMs?: number;
 };
-export type PhiServerAddonHookDescriptor = {
+/**
+ * How Core establishes that a hook request is from who it claims to be.
+ *
+ * A hook is unauthenticated by construction, and until Core could check a signature itself, "verified"
+ * was a thing each handler asserted about itself -- so the rule that a request with no actor may not
+ * write had to hold for every hook, including the ones that had in fact proved their caller. Stating the
+ * check here moves it in front of the handler: Core verifies over the raw body, and a handler that runs
+ * has already been vouched for.
+ *
+ * `secret` names one of this Add-on's own declared secrets, so the value an operator set is never in the
+ * manifest. `deliveryIdHeader` names the header the provider identifies a delivery with; where it is
+ * given, Core refuses a delivery it has already accepted, which is what makes a webhook retried after a
+ * timeout harmless.
+ */
+export type PhisAddonHookVerificationDescriptor = {
+    scheme: "hmac-sha256";
+    header: string;
+    /** What the header value is prefixed with, where it is -- GitHub sends `sha256=`. */
+    prefix?: string;
+    secret: string;
+    deliveryIdHeader?: string;
+};
+export type PhisAddonHookDescriptor = {
     id: string;
-    method: PhiServerAddonHttpMethod;
+    method: PhisAddonHttpMethod;
     path: string;
     handler: string;
     bodyLimitBytes: number;
     rateLimitClass: string;
     timeoutMs: number;
     /**
-     * Whether this hook is told which Site it was called for, through `x-phi-site-key`.
+     * How this hook's caller is checked, or absent where it cannot be.
+     *
+     * Absent is not a lesser variant of present: an unverified hook writes nothing at all -- not through
+     * `data:v1`, not by opening a thread -- because nothing distinguishes its caller from anybody who
+     * found the address. A hook that needs to write declares how it can be believed.
+     */
+    verification?: PhisAddonHookVerificationDescriptor;
+    /**
+     * Whether this hook is told which Site it was called for, through `x-phis-site-key`.
      *
      * A hook is unauthenticated by construction -- that is what makes it reachable by a payment provider
      * or by somebody else's Core. Without a Site it also has no capabilities at all, because every one of
@@ -50,7 +80,7 @@ export type PhiServerAddonHookDescriptor = {
      */
     siteScoped?: boolean;
 };
-export type PhiServerAddonCapabilityDescriptor = {
+export type PhisAddonCapabilityDescriptor = {
     id: string;
     interfaceDigest: string;
 };
@@ -62,14 +92,14 @@ export type PhiServerAddonCapabilityDescriptor = {
  * reaches the implementation without a dynamic import. The interface digest is checked against what
  * this release offers, so an Add-on built for an older interface is refused rather than called.
  */
-export type PhiServerAddonServiceProviderDescriptor = {
-    serviceKind: PhiServerServiceKind;
+export type PhisAddonServiceProviderDescriptor = {
+    serviceKind: PhisServiceKind;
     providerKey: string;
     interfaceDigest: string;
     factoryExport: string;
-    requiredCoreCapabilities: PhiServerCoreCapabilityId[];
+    requiredCoreCapabilities: PhisCoreCapabilityId[];
 };
-export type PhiServerAddonJobDescriptor = {
+export type PhisAddonJobDescriptor = {
     id: string;
     handler: string;
     /**
@@ -88,7 +118,7 @@ export type PhiServerAddonJobDescriptor = {
  * check a value against its type before it is stored -- the same bargain as the schema and query
  * descriptors, one step smaller.
  */
-export type PhiServerAddonSettingDescriptor = {
+export type PhisAddonSettingDescriptor = {
     name: string;
     type: "text" | "integer" | "boolean";
     /** Shown by the CLI when it lists what an Add-on can be configured with. */
@@ -107,8 +137,8 @@ export type PhiServerAddonSettingDescriptor = {
  * `siteAccess` names one of the Site's own claims; `role` names another role of this same Add-on. A
  * Site Admin may always grant any role of any Add-on, so a graph that reaches nobody still has a way in.
  */
-export type PhiServerAddonRoleGrantPolicy = {
-    siteAccess: PhiServerSiteAccess;
+export type PhisAddonRoleGrantPolicy = {
+    siteAccess: PhisSiteAccess;
 } | {
     role: string;
 };
@@ -122,23 +152,71 @@ export type PhiServerAddonRoleGrantPolicy = {
  * Core never interprets the name. It stores assignments, answers `has()`, and enforces `grantableBy`;
  * what `reviewer` means is the Add-on's business and stays there.
  */
-export type PhiServerAddonRoleDescriptor = {
+export type PhisAddonGroupWriterDescriptor = {
+    /**
+     * Who may cause this Add-on to create a group or change who is in one.
+     *
+     * The same policy shape a role's `grantableBy` uses, evaluated the same way, and with the same floor:
+     * a Site Admin always may, so a badly declared condition never locks a Site out of its own groups.
+     */
+    allowedBy: PhisAddonRoleGrantPolicy;
+};
+export type PhisAddonRoleDescriptor = {
+    name: string;
+    description?: string;
+    grantableBy: PhisAddonRoleGrantPolicy;
+};
+/**
+ * A group this Add-on needs on every Site that runs it.
+ *
+ * Groups are Core's vocabulary about shared rows, so an Add-on cannot invent one at runtime and cannot
+ * put anybody in it -- the groups capability reads and grants nothing. What it can do is say which ones
+ * it needs, and Core creates them per Site when the Site asks for the Add-on. Who is in them stays with
+ * whoever administers the Site, which is the point: a package should not be able to hand out standing.
+ *
+ * The group carries this Add-on's id as its provider, and Core already filters group claims against the
+ * available providers -- so an Add-on's group stops granting anything the moment the Add-on is gone,
+ * without anybody having to remember to clean up.
+ */
+export type PhisAddonGroupDescriptor = {
+    /** Unique within this Add-on. Frozen once a Site has one: memberships point at it by key. */
+    key: string;
+    /** What an administrator sees in the Site's group list. */
     name: string;
     description?: string;
-    grantableBy: PhiServerAddonRoleGrantPolicy;
 };
-export type PhiServerAddonManifestV1 = {
-    manifestVersion: typeof PHI_SERVER_ADDON_MANIFEST_VERSION;
+/**
+ * One event this Add-on wants to be told about.
+ *
+ * Declared like a route: Core reaches the handler by the name the runtime exports it under, so nothing
+ * registers itself and what an Add-on listens to is readable before it runs. Several handlers may name
+ * the same event; each is delivered separately and retried separately.
+ */
+export type PhisAddonEventHandlerDescriptor = {
+    id: string;
+    event: PhisAddonEventId;
+    handler: string;
+};
+export type PhisAddonManifestV1 = {
+    manifestVersion: typeof PHIS_ADDON_MANIFEST_VERSION;
     addonId: string;
     packageName: string;
     packageVersion: string;
     serverAbi: string;
-    capabilities: PhiServerAddonCapabilityDescriptor[];
-    serviceProviders: PhiServerAddonServiceProviderDescriptor[];
-    requiredCoreCapabilities: PhiServerCoreCapabilityId[];
-    apiRoutes: PhiServerAddonApiRouteDescriptor[];
-    hooks: PhiServerAddonHookDescriptor[];
-    jobs: PhiServerAddonJobDescriptor[];
+    capabilities: PhisAddonCapabilityDescriptor[];
+    serviceProviders: PhisAddonServiceProviderDescriptor[];
+    requiredCoreCapabilities: PhisCoreCapabilityId[];
+    apiRoutes: PhisAddonApiRouteDescriptor[];
+    hooks: PhisAddonHookDescriptor[];
+    jobs: PhisAddonJobDescriptor[];
+    /**
+     * The events this Add-on wants delivered. Absent means none.
+     *
+     * Optional like every field added after this manifest version was in the wild. Declaring one is not
+     * receiving it: an event reaches this Add-on only for a thread it holds a synced link to, so an
+     * Add-on that declares them and links nothing is told nothing.
+     */
+    eventHandlers?: PhisAddonEventHandlerDescriptor[];
     /**
      * What an operator may configure. Absent means nothing is.
      *
@@ -148,7 +226,7 @@ export type PhiServerAddonManifestV1 = {
      * fields may demand an explicit `null`, because no stored manifest predates them; later ones must
      * define what absence means and accept it.
      */
-    settings?: PhiServerAddonSettingDescriptor[];
+    settings?: PhisAddonSettingDescriptor[];
     /**
      * The roles this Add-on defines. Absent means it defines none.
      *
@@ -156,14 +234,50 @@ export type PhiServerAddonManifestV1 = {
      * forgotten it. A name is frozen from the first assignment -- renaming one orphans every grant that
      * points at it, silently, because the grant is stored as text and text does not follow a rename.
      */
-    roles?: PhiServerAddonRoleDescriptor[];
+    roles?: PhisAddonRoleDescriptor[];
+    /**
+     * The groups this Add-on needs. Absent means none.
+     *
+     * Optional like every field added after the manifest version was in the wild, and absent means the
+     * Add-on asks for no group rather than that it forgot to say so.
+     */
+    groups?: PhisAddonGroupDescriptor[];
+    /**
+     * Whether this Add-on may create groups of its own while it runs, and who may cause it to.
+     *
+     * The declared list above is for the groups a Site always has -- one per Add-on, known when the
+     * manifest was written. This is for the ones a Site produces as it runs: one per vendor, per team, per
+     * tenant, whose number and names nobody knew in advance.
+     *
+     * It stays a declaration rather than a capability an Add-on simply has, for the reason `grantableBy`
+     * exists: the manifest is covered by a digest the running code cannot rewrite, so the author states
+     * who may cause a group, and Core decides whether the condition is met. Without it, "an Add-on may
+     * make groups" would mean "an Add-on may make itself an authority container and fill it".
+     *
+     * What it may do is bounded by ownership either way: a group it creates carries its own id as the
+     * provider, and every write here refuses a group carrying anybody else's.
+     */
+    groupWriter?: PhisAddonGroupWriterDescriptor;
+    /**
+     * The Modules this package's other half contributes. Absent means it has no Module half.
+     *
+     * Each id is `<package name>/<module key>`, and the package name is this manifest's own -- one package
+     * carries one product, so there is nothing to resolve. What the field adds is the one thing Core
+     * cannot see from an artifact: whether a Module half exists at all. An Add-on that is only an Add-on,
+     * like a storage provider, says nothing here and is complete on its own.
+     *
+     * It is what lets enabling an Add-on for a Site check that the Site actually has the other half. A
+     * Site with the Add-on and not the Module has routes with no surface: nothing is broken, but an
+     * operator who thinks they switched a feature on finds nothing.
+     */
+    modules?: string[];
     /**
      * The tables this Add-on owns, or null when it owns none.
      *
      * There is no list of migration steps beside it. The descriptor is the desired shape; what has been
      * applied is recorded in the database, and Core derives the difference.
      */
-    schema: PhiServerAddonSchemaDescriptor | null;
+    schema: PhisAddonSchemaDescriptor | null;
     /**
      * The statements this Add-on may run against its own tables, or null when it runs none.
      *
@@ -172,14 +286,14 @@ export type PhiServerAddonManifestV1 = {
      *
      * Optional for the reason `settings` is: it arrived after the manifest version was in the wild.
      */
-    queries?: PhiServerAddonQueryCatalog | null;
+    queries?: PhisAddonQueryCatalog | null;
     /** The version of `schema`, or 0 when there is none. */
     migrationVersion: number;
 };
-export type PhiServerAddonRequestContext = {
+export type PhisAddonRequestContext = {
     addonId: string;
     requestId: string;
-    method: PhiServerAddonHttpMethod;
+    method: PhisAddonHttpMethod;
     url: string;
     headers: Headers;
     body: Uint8Array;
@@ -188,6 +302,15 @@ export type PhiServerAddonRequestContext = {
     site: {
         id: number;
         key: string;
+        /**
+         * Where this Site answers from, as the outside world reaches it.
+         *
+         * Core's own addresses are Site-relative, which is right for a page of that Site and useless in
+         * anything that leaves it: a listing another Core fetches, a link in an email, a picture in a
+         * feed. A handler cannot derive this -- a request carries the host it happened to arrive on, and
+         * an internal one carries none at all -- so it is the Site's own record that says it.
+         */
+        publicBaseUrl: string;
     } | null;
     actor: {
         kind: "operator";
@@ -205,10 +328,10 @@ export type PhiServerAddonRequestContext = {
      * Only what the manifest declared arrives. A capability is not fetched, looked up, or constructed by
      * the Add-on -- it is here or it is not, and it was already decided before the handler ran.
      */
-    capabilities: PhiServerAddonCapabilities;
+    capabilities: PhisAddonCapabilities;
     signal: AbortSignal;
 };
-export type PhiServerAddonHandler = (context: PhiServerAddonRequestContext) => Promise<Response> | Response;
+export type PhisAddonHandler = (context: PhisAddonRequestContext) => Promise<Response> | Response;
 /**
  * A service factory, as the runtime exports it.
  *
@@ -216,24 +339,25 @@ export type PhiServerAddonHandler = (context: PhiServerAddonRequestContext) => P
  * what makes that agreement checkable. The factory receives schema-validated profile configuration and
  * a restricted context, never a database handle or a general secret accessor.
  */
-export type PhiServerAddonServiceFactory = (config: unknown, context: unknown) => unknown;
-export type PhiServerAddonRuntimeV1 = {
-    manifest: PhiServerAddonManifestV1;
-    apiHandlers?: Readonly<Record<string, PhiServerAddonHandler>>;
-    hookHandlers?: Readonly<Record<string, PhiServerAddonHandler>>;
-    serviceFactories?: Readonly<Record<string, PhiServerAddonServiceFactory>>;
-    jobHandlers?: Readonly<Record<string, PhiServerAddonJobHandler>>;
+export type PhisAddonServiceFactory = (config: unknown, context: unknown) => unknown;
+export type PhisAddonRuntimeV1 = {
+    manifest: PhisAddonManifestV1;
+    apiHandlers?: Readonly<Record<string, PhisAddonHandler>>;
+    hookHandlers?: Readonly<Record<string, PhisAddonHandler>>;
+    serviceFactories?: Readonly<Record<string, PhisAddonServiceFactory>>;
+    jobHandlers?: Readonly<Record<string, PhisAddonJobHandler>>;
+    eventHandlers?: Readonly<Record<string, PhisAddonEventHandler>>;
 };
-export type PhiServerAddonRuntimeModuleV1 = {
-    phiServerAddon: PhiServerAddonRuntimeV1;
+export type PhisAddonRuntimeModuleV1 = {
+    phisAddon: PhisAddonRuntimeV1;
 };
-export type PhiServerAddonBuildEntry = {
+export type PhisAddonBuildEntry = {
     enabled: boolean;
     manifestDigest: string;
-    manifest: PhiServerAddonManifestV1;
-    load: () => Promise<PhiServerAddonRuntimeModuleV1>;
+    manifest: PhisAddonManifestV1;
+    load: () => Promise<PhisAddonRuntimeModuleV1>;
 };
-export type PhiServerAddonBuildManifest = Readonly<Record<string, PhiServerAddonBuildEntry>>;
+export type PhisAddonBuildManifest = Readonly<Record<string, PhisAddonBuildEntry>>;
 /**
  * One installed Add-on, as the operator's desired state records it.
  *
@@ -242,7 +366,7 @@ export type PhiServerAddonBuildManifest = Readonly<Record<string, PhiServerAddon
  * digests bind the three apart: `manifestDigest` covers the descriptors below, `artifactDigest` covers
  * the file in the install root, and the loader refuses a file that no longer matches.
  */
-export type PhiServerAddonDesiredStateEntry = {
+export type PhisAddonDesiredStateEntry = {
     addonId: string;
     packageName: string;
     packageVersion: string;
@@ -250,10 +374,10 @@ export type PhiServerAddonDesiredStateEntry = {
     /** SHA-256 of the installed artifact, and the cache key its load address carries. */
     artifactDigest: string;
     /** The validated descriptors, as read from the artifact at installation. */
-    manifest: PhiServerAddonManifestV1;
+    manifest: PhisAddonManifestV1;
     enabled: boolean;
 };
-export type PhiServerAddonDesiredState = {
+export type PhisAddonDesiredState = {
     formatVersion: 1;
-    addons: PhiServerAddonDesiredStateEntry[];
+    addons: PhisAddonDesiredStateEntry[];
 };

package/dist/addon.js

@@ -11,5 +11,5 @@
  * no node builtins -- the Add-on states, and Core checks. If something here ever does more than hand
  * back a constant, it is in the wrong package.
  */
-export const PHI_SERVER_ADDON_MANIFEST_VERSION = 1;
-export const PHI_SERVER_ADDON_ABI_VERSION = 1;
+export const PHIS_ADDON_MANIFEST_VERSION = 1;
+export const PHIS_ADDON_ABI_VERSION = 1;

package/dist/assets.d.ts

@@ -0,0 +1,165 @@
+import type { PhiMediaUploadPlan } from "./media-storage.js";
+/**
+ * Files on a row: `@phis/server/assets:v1`.
+ *
+ * The slots are declared in the schema descriptor -- a name, a cardinality, a size ceiling, the media
+ * types it takes, who may fetch it -- and this is how they are filled. An Add-on says which row and
+ * which slot; where the object goes, what it is called and whether it arrived are Core's answers.
+ *
+ * There is one upload lifecycle in Core and this is not a second one. Core reserves, receives, measures
+ * and hashes without knowing who asked; the purpose stated here is read back at the last step, where
+ * the finished object becomes a row in the Add-on's table.
+ *
+ * **No method takes an object key and none returns one.** A key an Add-on chooses is a key Core cannot
+ * recognise later, and an object Core cannot recognise is one it can neither deliver nor account for.
+ * What comes back instead is a Media Asset id, which the delivery Core already has takes.
+ */
+export type PhisAddonAssetView = {
+    id: string;
+    slot: string;
+    ownerId: string;
+    /** The file itself, as Core records it. */
+    mediaAssetId: number;
+    /**
+     * Where the file is served from, Site-relative, as Core addresses its own Media.
+     *
+     * Given rather than left to be composed, because composing it means knowing two things an Add-on has
+     * no way to be told: the route, and the cache revision it carries. A path built without the revision
+     * still delivers the file and never gets an immutable cache -- every viewer revalidates every time,
+     * and nothing about the result looks wrong enough to investigate.
+     *
+     * Read at the moment it is used, never stored. The revision rotates whenever the file's delivery
+     * changes, and a path kept from an earlier read would then be the stale one it exists to retire.
+     *
+     * What the path answers with is the slot's `delivery`: `public` to anyone, `authenticated` to a
+     * session, `internal` only to Core's own caller. The address is not the permission.
+     */
+    contentPath: string;
+    byteSize: number;
+    contentType: string;
+    /**
+     * The digest that was established, with the algorithm that produced it -- or null where none was.
+     *
+     * Established means one of two things: the endpoint verified what the client stated and would have
+     * refused anything else, or Core received the body and hashed it in flight. Null is a truthful "not
+     * established" -- an `etag` is an HTTP header and not a content hash, and a wrong digest here would
+     * be worse than none, because it invites a comparison.
+     *
+     * The algorithm is part of the answer and not an assumption. Which one an endpoint can attest to
+     * differs between Providers, so a bare value would be a number whose meaning the reader has to guess.
+     */
+    checksum: {
+        algorithm: string;
+        value: string;
+    } | null;
+    createdAt: string;
+};
+/**
+ * A place made for a file, and how to deliver it.
+ *
+ * The plan is the Provider's answer, not Core's: an endpoint that can take a body directly says so, and
+ * one that cannot names a Core route to stream through. An Add-on passes it to its client unread.
+ */
+export type PhisAddonAssetReservationView = {
+    /** What the transfer is carried out against, and what `finalize` is called with. */
+    token: string;
+    plan: PhiMediaUploadPlan;
+    expiresAt: string;
+};
+export type PhisAssetsCapabilityV1 = {
+    /**
+     * Reserves a place for a file, before any of it is sent.
+     *
+     * The size is stated now and held to later, and the space is charged now rather than at the end. A
+     * ceiling decided at the end would bound the bookkeeping and not the store: ten clients could each
+     * write a gigabyte and have five of them refused afterwards, with the bytes already paid for.
+     *
+     * `sha256` is the client's statement of what it is about to send. Where the Storage Profile was found
+     * to verify one, it is signed into the plan and the endpoint refuses anything else -- so a wrong
+     * digest never becomes an object, and Core can record the figure as true without having seen a byte.
+     * Where it was not, the body comes through Core and Core hashes it instead.
+     *
+     * Refused where the slot is not declared, where the type is not one it takes, where the size is over
+     * the slot's ceiling or the Site's, where the Space is full, and where the acting user may not change
+     * the row. Attaching a file to a row changes it, so it is the row's authority that decides.
+     */
+    begin(input: {
+        table: string;
+        ownerId: string | number;
+        slot: string;
+        contentType: string;
+        sizeBytes: number;
+        sha256?: string;
+        /** What the file was called where it came from. Core makes one up when there is nothing to use. */
+        filename?: string;
+    }): Promise<PhisAddonAssetReservationView>;
+    /**
+     * Settles a reservation once the bytes are there, and makes the file a row.
+     *
+     * Core looks at what actually landed rather than believing the report: nothing there is not a file,
+     * and a different size than was reserved is not a file either. On a single-valued slot the file being
+     * replaced goes in the same transaction -- there is no moment in which the row holds two.
+     *
+     * Repeating it is safe. A client whose answer was lost cannot tell a finished upload from a failed
+     * one, so a second call answers with the same file rather than with an error.
+     */
+    finalize(input: {
+        table: string;
+        token: string;
+        /** Whatever the plan's issuer asked the client to bring back. Core passes it through unread. */
+        completion?: unknown;
+    }): Promise<PhisAddonAssetView>;
+    /** Gives an unredeemed reservation up. An abandoned one expires on its own; this is the tidy path. */
+    abandon(input: {
+        table: string;
+        token: string;
+    }): Promise<boolean>;
+    /**
+     * The files of a row. A reservation in flight is not among them, because it is not a file yet.
+     *
+     * Refused where the acting user may not read the row. Asking what a row carries is reading the row,
+     * and a slot's `delivery` does not answer it: a file whose id, name and size come back to anyone has
+     * already given up most of what `internal` was keeping.
+     */
+    list(input: {
+        table: string;
+        ownerId: string | number;
+        slot?: string;
+    }): Promise<PhisAddonAssetView[]>;
+    /**
+     * Takes a file out of its slot, and the file with it.
+     *
+     * Refused where the acting user may not change the row, which is the same authority `begin` is
+     * measured against -- taking a file away changes the row exactly as putting one there does. A file
+     * that is not there answers `false` rather than refusing, because a refusal would say it exists.
+     */
+    remove(input: {
+        table: string;
+        id: string;
+    }): Promise<boolean>;
+    /**
+     * What this Add-on's files take up on this Site, and what they are allowed to.
+     *
+     * Here for the reason `storage:v1` has the same call: the ceiling is the operator's and Core enforces
+     * it whether or not anybody read this first, so this exists to let an Add-on say *why*. A refusal an
+     * interface can explain before a person picks a file beats one that arrives after they waited for the
+     * upload, and a vendor who can see they are at their limit does not report it as a fault.
+     *
+     * The two figures are separate because both are spent. `bytes` is what is stored; `reservedBytes` is
+     * held for uploads in flight and is as unavailable as stored bytes until they finish or lapse. Room
+     * for one more file is `quotaBytes - (bytes + reservedBytes)`, which is the comparison `begin` makes.
+     *
+     * `quotaBytes` is the effective ceiling after inheritance -- the Space's own override where there is
+     * one, the Site's default for Add-on Spaces otherwise -- so it is the figure that will actually be
+     * applied and not a raw column. `null` means no ceiling. An explicit `0` is a revocation, not an
+     * absence.
+     *
+     * No object count, unlike `storage:v1`. Core keeps a running total of bytes and none of files, and
+     * counting them on demand would be the unbounded read the ceiling exists to prevent.
+     */
+    usage(): Promise<{
+        bytes: number;
+        reservedBytes: number;
+        quotaBytes: number | null;
+    }>;
+};

package/dist/assets.js

@@ -0,0 +1 @@
+export {};