@wtfalch/files 0.9.1 → 0.11.1

package/README.md

@@ -6,7 +6,7 @@ package dependencies.
 
 ## Status
 
-Published: yes, v0.9.1, 2026-09-28.
+Published: yes, v0.11.0, 2026-10-03.
 
 ```sh
 npm install @wtfalch/files
@@ -50,7 +50,8 @@ exact file version. A mismatch against the file's current version throws
 `ApiError` with `status: 409` rather than serving the current version's
 bytes -- the backend keeps only the current version's object, so there is no
 older version to fall back to. Every `StoredFile` also carries `sha256`
-(`null` unless the storage backend exposed byte access at confirm time) and
+(`null` unless the storage backend exposed byte access at confirm time),
+`createdAt` (ISO 8601 creation time of the file row) and
 `principalRef`, the principal whose upload last confirmed it at its current
 version (`null` if that upload is no longer on record, or the file was never
 confirmed).
@@ -188,6 +189,11 @@ app key), so lokessmie's and offline.tf's existing app-key integrations keep
 minting links unchanged. Change it afterward with `setFileAudience`'s own
 `shareable` field.
 
+A link's `expiresAt` is `null` for a link that never stops working, or a time
+at most 365 days ahead (a few minutes more are allowed for a caller's clock
+running ahead). That is the range of an app's `FILES_SHARE_LINK_DAYS`
+(1 to 365, or `never`): send `now + days`, or `null` for `never`.
+
 ### Seeing everything: `files.files:read-any`
 
 A sensitive permission: read any file in the organisation, whatever its
@@ -251,13 +257,16 @@ is a separate rollout; installing the SDK does not migrate accounts or files.
 
 ## Calling from a browser through a same-origin proxy
 
-The files host itself has no CORS headers and no public domain (task #70):
 `credential()` above must never be a privileged service credential in
-browser code, and a browser cannot reach the host directly either way. A
-browser app such as Agora instead runs its own same-origin proxy -- a route
-on the app's own origin that forwards `Authorization` and
-`X-Organisation-Id` to the files host on its private network, stripping any
-cookies -- and points the SDK at itself:
+browser code. The host now answers a CORS preflight and allows a direct
+browser call for an origin its operator has allow-listed
+(`FILES_ALLOWED_ORIGINS` -- see `@wtfalch/files-host`'s README, "Cross-origin
+browser calls"); point `createFilesClient` at the host's own URL in that
+case. For any other origin, or before it is allow-listed, the host has no
+public domain for it to reach anyway, so a browser app such as Agora instead
+runs its own same-origin proxy -- a route on the app's own origin that
+forwards `Authorization` and `X-Organisation-Id` to the files host on its
+private network, stripping any cookies -- and points the SDK at itself:
 
 ```ts
 const files = createFilesClient({
@@ -397,6 +406,84 @@ every row and every stored object -- and `restoreOrganisation` then throws
 `ApiError` with `status: 404` too, the same as for an organisation that was
 never deleted; the two are not distinguishable from the client, by design.
 
+### Quotas and budgets: operator ceiling vs. organisation limit
+
+Two different levels cap an organisation's bytes and spend, and only one of
+them is operator-settable. `updateOrganisationCeiling` sets the operator
+**ceiling** (`ceilingBytes`/`ceilingMicros`) -- the platform-wide cap a
+support/operator credential may set for any organisation, passed by
+`organisationId` like the rest of the organisation-management calls above.
+`getQuota`/`setQuota`/`getBudget`/`setBudget` work on the organisation's own
+**limit** (`limitBytes`/`limitMicros`) instead, and are tenant self-service
+only: they take no `organisationId` because the target is always read off
+the signed request's own identity, never a parameter a caller can point
+elsewhere.
+
+```ts
+// Operator-settable, any organisation, by id:
+await management.updateOrganisationCeiling(organisationId, { ceilingBytes: '5000000000' });
+
+// Tenant self-service, the caller's own organisation only:
+const tenantManagement = createFilesManagementClient({ url, fetch: tenantFetch });
+await tenantManagement.setQuota('1000000000');
+await tenantManagement.setBudget('250000000');
+```
+
+There is no operator-callable way to set an organisation's own limit on its
+behalf. This was decided deliberately (issue #116): a freshly provisioned
+organisation's limit starts `null` (uncapped at that level), so the operator
+ceiling alone governs it until the organisation sets a tighter limit for
+itself, from its own tenant application (for example Boule). An application
+provisioning an organisation on an operator's behalf (Archon's foundry step,
+for one) should set the ceiling and stop there -- not attempt to also seed
+the organisation's own limit, which no credential it holds can do.
+
+### One app's files (issue #161)
+
+A company's admin app (Boule) reads one app's files with a key of the
+company's own organisation: `appFilesTotals`, `appFilesFolders`,
+`appFilesSpace`, `appFiles` and `appFilesLinks`, and `stopSharing` to revoke
+a link. Every call names the app's collections by name and reads only those;
+the organisation is always the key's own. Files knows no apps and no copies:
+a workspace is its own organisation, read with its own key. The key needs
+`files.usage:read` (totals, folders, space), `files.files:read` (the files
+list), `files.shares:read` (the links) and `files.files:share` (Stop sharing),
+each across the organisation.
+
+```ts
+const app = { collections: ['INVOICES', 'PHOTOS'] };
+const totals = await tenantManagement.appFilesTotals(app);
+const { files, more } = await tenantManagement.appFiles({ ...app, search: 'march', limit: 50 });
+await tenantManagement.stopSharing({ ...app, link: linkId });
+```
+
+### An app's space alert (issue #164)
+
+Foundry sets each app's `spaceAlertPercent` with the operator's management
+key (`files.organisations:provision`, the permission that ensures the app's
+collections): `setSpaceAlert(organisationId, app, { percent, name,
+collections, recipients })` (PUT
+`/v1/manage/organisations/:organisationId/apps/:app/space-alert`),
+`getSpaceAlert` (GET) and `removeSpaceAlert` (DELETE, a no-op when there is
+none). `app` is the entry key, `percent` is 1 to 100 and defaults to 80,
+`collections` are the app's collection names (1 to 50) and `recipients` the
+owners' addresses (at most 20); files keeps no address for anyone, so
+foundry sends the setting again when the owners change. Every day, after the
+meter, files mails each recipient once when the bytes of the app's live files
+reach `percent` of the organisation's plan space (the tighter of its limit and
+the operator ceiling, `planBytes` in the totals), and again only after they
+drop below it and reach it again. A send that fails is tried on the next day's
+check; nobody is mailed twice for one crossing.
+
+```ts
+await management.setSpaceAlert(organisationId, 'shop', {
+  percent: 80,
+  name: 'Shop',
+  collections: ['INVOICES', 'PHOTOS'],
+  recipients: ['owner@acme.example'],
+});
+```
+
 ### Membership
 
 The product that owns its users (Agora, lokessmie) writes memberships in its

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ClientOptions, type ManagementClientOptions } from './transport.js';
-import type { AddMemberInput, AuditPage, AuditQuery, BudgetSummary, CopyFileInput, CreatedShare, FilesPage, FilesRate, Group, GroupMember, Member, MoveFileInput, OrganisationShare, OrganisationSummary, ProvisionOrganisationInput, ProvisionOrganisationResult, QuotaSummary, SetFileAudienceInput, SetRateInput, SetWebhookResult, Share, SharedFilesPage, StoredFile, UpdateOrganisationCeilingInput, UploadInput, UploadReservation, UploadedPart, UsageDay, VariantFormat, VariantWidth, WebhookConfig } from './types.js';
+import type { AddMemberInput, AppFilesEntry, AppFilesFolder, AppFilesLink, AppFilesListQuery, AppFilesQuery, AppFilesSpace, AppFilesTotals, AuditPage, AuditQuery, BudgetSummary, CopyFileInput, CreatedShare, FilesPage, FilesRate, Group, GroupMember, IssueKeyInput, IssueOrganisationKeyInput, IssuedOrganisationKey, Member, MoveFileInput, OrganisationShare, OrganisationSummary, ProvisionOrganisationInput, ProvisionOrganisationResult, QuotaSummary, RevokedOrganisationKey, SetFileAudienceInput, SetRateInput, SetSpaceAlertInput, SetWebhookResult, Share, SharedFilesPage, SpaceAlert, StoredFile, UpdateOrganisationCeilingInput, UploadInput, UploadReservation, UploadedPart, UsageDay, VariantFormat, VariantWidth, WebhookConfig } from './types.js';
 export { ApiError, type ClientOptions, type ManagementClientOptions } from './transport.js';
 export declare function createFilesClient(options: ClientOptions): {
     createCollection: (name: string) => Promise<{
@@ -122,6 +122,26 @@ export declare function createFilesManagementClient(options: ManagementClientOpt
         organisations: OrganisationSummary[];
     }>;
     provisionOrganisation: (input: ProvisionOrganisationInput) => Promise<ProvisionOrganisationResult>;
+    issueOrganisationKey: (organisationId: string, input: IssueOrganisationKeyInput) => Promise<IssuedOrganisationKey>;
+    revokeOrganisationKey: (organisationId: string, keyId: string) => Promise<RevokedOrganisationKey>;
+    issueKeyBelow: (organisationId: string, minterId: string, input: IssueKeyInput) => Promise<IssuedOrganisationKey>;
+    ensureCollection: (organisationId: string, name: string) => Promise<{
+        created: boolean;
+        id: string;
+        name: string;
+    }>;
+    setSpaceAlert: (organisationId: string, app: string, input: SetSpaceAlertInput) => Promise<{
+        created: boolean;
+        app: string;
+        name: string;
+        percent: number;
+        collections: string[];
+        recipients: string[];
+        above: boolean;
+        updatedAt: string;
+    }>;
+    getSpaceAlert: (organisationId: string, app: string) => Promise<SpaceAlert>;
+    removeSpaceAlert: (organisationId: string, app: string) => Promise<void>;
     updateOrganisationCeiling: (organisationId: string, input: UpdateOrganisationCeilingInput) => Promise<OrganisationSummary>;
     deleteOrganisation: (organisationId: string) => Promise<OrganisationSummary>;
     restoreOrganisation: (organisationId: string) => Promise<OrganisationSummary>;
@@ -137,8 +157,28 @@ export declare function createFilesManagementClient(options: ManagementClientOpt
     listOrganisationShares: () => Promise<{
         shares: OrganisationShare[];
     }>;
+    appFilesTotals: (query: AppFilesQuery) => Promise<AppFilesTotals>;
+    appFilesFolders: (query: AppFilesQuery) => Promise<{
+        folders: AppFilesFolder[];
+    }>;
+    appFilesSpace: (query: AppFilesQuery) => Promise<AppFilesSpace>;
+    appFiles: (query: AppFilesListQuery) => Promise<{
+        files: AppFilesEntry[];
+        more: boolean;
+    }>;
+    appFilesLinks: (query: AppFilesQuery & {
+        limit?: number;
+    }) => Promise<{
+        links: AppFilesLink[];
+        total: number;
+    }>;
+    stopSharing: (query: AppFilesQuery & {
+        link: string;
+    }) => Promise<void>;
     getWebhook: () => Promise<WebhookConfig>;
     setWebhook: (url: string | null) => Promise<SetWebhookResult>;
+    issueKey: (input: IssueKeyInput) => Promise<IssuedOrganisationKey>;
+    revokeKey: (keyId: string) => Promise<RevokedOrganisationKey>;
     listMembers: () => Promise<{
         members: Member[];
     }>;

package/dist/client.js

@@ -139,6 +139,32 @@ export function createFilesManagementClient(options) {
             const { data, status } = await callWithStatus('POST', '/v1/manage/organisations', input);
             return { ...data, created: status === 201 };
         },
+        // Mints an organisation's root key; the secret comes back once. Throws
+        // `ApiError` 409 for an organisation with no owner, 422 when the issuer
+        // is not a member or lacks a requested permission.
+        issueOrganisationKey: (organisationId, input) => call('POST', `/v1/manage/organisations/${encodeURIComponent(organisationId)}/keys`, input),
+        // Revokes the key and every key it minted; a second call is a no-op.
+        revokeOrganisationKey: (organisationId, keyId) => call('DELETE', `/v1/manage/organisations/${encodeURIComponent(organisationId)}/keys/${encodeURIComponent(keyId)}`),
+        // Mints a key below `minterId`, a live key of the organisation, without the
+        // minter's secret. Same input, result and errors as `issueKey`, plus 404
+        // when `minterId` is not a live key of the organisation. Revoking the
+        // minter (`revokeOrganisationKey`) revokes the new key too.
+        issueKeyBelow: (organisationId, minterId, input) => call('POST', `/v1/manage/organisations/${encodeURIComponent(organisationId)}/keys/${encodeURIComponent(minterId)}/keys`, input),
+        // Returns the organisation's collection of that name, creating it when
+        // missing; `created` is true only on the call that made it.
+        ensureCollection: async (organisationId, name) => {
+            const { data, status } = await callWithStatus('POST', `/v1/manage/organisations/${encodeURIComponent(organisationId)}/collections`, { name });
+            return { ...data, created: status === 201 };
+        },
+        // An app's space alert (issue #164). `created` is true only on the call
+        // that made it. `getSpaceAlert` throws `ApiError` 404 when there is none;
+        // `removeSpaceAlert` is a no-op when there is none.
+        setSpaceAlert: async (organisationId, app, input) => {
+            const { data, status } = await callWithStatus('PUT', spaceAlertPath(organisationId, app), input);
+            return { ...data, created: status === 201 };
+        },
+        getSpaceAlert: (organisationId, app) => call('GET', spaceAlertPath(organisationId, app)),
+        removeSpaceAlert: (organisationId, app) => call('DELETE', spaceAlertPath(organisationId, app)),
         updateOrganisationCeiling: (organisationId, input) => call('PATCH', `/v1/manage/organisations/${encodeURIComponent(organisationId)}`, input),
         // Delete an organisation with a 7-day grace period (task O, issue #67).
         // Idempotent: deleting an already-deleted organisation succeeds again
@@ -153,6 +179,10 @@ export function createFilesManagementClient(options) {
         restoreOrganisation: (organisationId) => call('POST', `/v1/manage/organisations/${encodeURIComponent(organisationId)}/restore`),
         // Tenant routes (task S4b): the caller's own organisation, from the
         // signed request's claim -- there is no organisation id to pass here.
+        // Self-service only, by design (issue #116): there is no
+        // operator-callable variant that targets another organisation's own
+        // limit. An operator sets only the ceiling, updateOrganisationCeiling
+        // above. See the SDK README's "Quotas and budgets" section.
         getQuota: () => call('GET', '/v1/manage/quota'),
         setQuota: (limitBytes) => call('PUT', '/v1/manage/quota', { limitBytes }),
         setKeyQuota: (keyId, limitBytes) => call('PUT', `/v1/manage/keys/${encodeURIComponent(keyId)}/quota`, {
@@ -167,9 +197,27 @@ export function createFilesManagementClient(options) {
         // Public share links (task S6): every active link in the caller's
         // organisation, with the file's name -- never the token or URL.
         listOrganisationShares: () => call('GET', '/v1/manage/shares'),
+        // One app's files (issue #161): only the named collections of the
+        // caller's own organisation.
+        appFilesTotals: (query) => call('GET', `/v1/manage/report/totals?${reportParams(query)}`),
+        appFilesFolders: (query) => call('GET', `/v1/manage/report/folders?${reportParams(query)}`),
+        appFilesSpace: (query) => call('GET', `/v1/manage/report/space?${reportParams(query)}`),
+        appFiles: (query) => call('GET', `/v1/manage/report/files?${reportParams(query)}`),
+        appFilesLinks: (query) => call('GET', `/v1/manage/report/links?${reportParams(query)}`),
+        // Stop sharing: the link stops opening at once. A link outside the named
+        // collections is not found.
+        stopSharing: (query) => call('DELETE', `/v1/manage/report/links/${encodeURIComponent(query.link)}?${reportParams({ collections: query.collections })}`),
         // Outbound event delivery (task gap-36). setWebhook(null) disables it.
         getWebhook: () => call('GET', '/v1/manage/webhook'),
         setWebhook: (url) => call('PUT', '/v1/manage/webhook', { url }),
+        // Mints a key below the calling key (which needs `credentials:create`);
+        // the secret comes back once. Throws `ApiError` 422 for a permission the
+        // caller lacks, `credentials:create`/`credentials:revoke`, or an expiry
+        // or limit past the caller's own; 404 when the caller may not mint.
+        issueKey: (input) => call('POST', '/v1/manage/keys', input),
+        // Revokes a key of the caller's own subtree (the caller included) and
+        // every key it minted; 404 for any other key. A second call is a no-op.
+        revokeKey: (keyId) => call('DELETE', `/v1/manage/keys/${encodeURIComponent(keyId)}`),
         // Membership (task M): the product that owns its users writes
         // memberships in its own files organisation. `files.members:read`/
         // `files.members:update`, held by the calling key for its own
@@ -184,3 +232,17 @@ export function createFilesManagementClient(options) {
         removeMember: (subject) => call('DELETE', `/v1/manage/members/${encodeURIComponent(subject)}`),
     };
 }
+/** `collection=A&collection=B&...` plus the list query's own fields. */
+function reportParams(query) {
+    const params = new URLSearchParams();
+    for (const name of query.collections)
+        params.append('collection', name);
+    if (query.folder)
+        params.set('folder', query.folder);
+    if (query.search)
+        params.set('search', query.search);
+    if (query.limit !== undefined)
+        params.set('limit', String(query.limit));
+    return params;
+}
+const spaceAlertPath = (organisationId, app) => `/v1/manage/organisations/${encodeURIComponent(organisationId)}/apps/${encodeURIComponent(app)}/space-alert`;

package/dist/types.d.ts

@@ -92,6 +92,8 @@ export interface StoredFile {
     bytes: string;
     version: number;
     collectionId: string;
+    /** When the file row was created (ISO 8601). */
+    createdAt: string;
     expiresAt: string | null;
     /** `"md5:<hex>"` of the confirmed bytes, or `null` for a file confirmed
      * before this field existed. Derived from the storage backend's own etag
@@ -269,6 +271,46 @@ export interface ProvisionOrganisationResult extends OrganisationSummary {
         secret: string;
     };
 }
+export interface IssueOrganisationKeyInput {
+    name: string;
+    kind: 'api_key' | 'agent' | 'service';
+    /** Subject id of a live human member of the organisation; the key holds
+     * only permissions that person holds. */
+    issuer: string;
+    permissions: string[];
+    /** 1 to 365. */
+    expiresDays: number;
+    app?: string;
+}
+export interface IssuedOrganisationKey {
+    id: string;
+    /** Shown once; files keeps no copy. */
+    secret: string;
+    kind: 'api_key' | 'agent' | 'service';
+    expiresAt: string;
+    permissions: string[];
+}
+export interface RevokedOrganisationKey {
+    id: string;
+    /** The key and every key it minted; empty when it was already revoked. */
+    revoked: string[];
+}
+export interface IssueKeyInput {
+    name: string;
+    kind: 'api_key' | 'agent' | 'service';
+    /** Each must be held by the calling key; never `credentials:create` or `credentials:revoke`. */
+    permissions: string[];
+    /** 1 to 365, and not past the calling key's own expiry. */
+    expiresDays: number;
+    /** Defaults to the calling key's own app. */
+    app?: string;
+    /** Byte quota for the new key, at most the organisation's limit; `null` is uncapped. */
+    limitBytes?: number | null;
+    /** Spend limit in micros for the new key, at most the organisation's limit; `null` is uncapped. */
+    limitMicros?: number | null;
+}
+export type IssuedKey = IssuedOrganisationKey;
+export type RevokedKey = RevokedOrganisationKey;
 export interface UpdateOrganisationCeilingInput {
     ceilingBytes?: string | null;
     ceilingMicros?: string | null;
@@ -400,3 +442,103 @@ export interface AuditPage {
     events: AuditEvent[];
     next: string | null;
 }
+/** One app's files, read by the company's own admin app (issue #161): every
+ * call names the app's collections by name (the `collections` of foundry's
+ * `files` module) and reads only those, inside the one organisation the key
+ * belongs to. Files has no notion of an app or of a copy (live or
+ * workspace): a copy is its own organisation, read with that organisation's
+ * key. Bytes and counts are JSON numbers; times are ISO, days `YYYY-MM-DD`
+ * in UTC. */
+export interface AppFilesQuery {
+    /** The app's collections, by name. 1 to 50. */
+    collections: string[];
+}
+export interface AppFilesTotals {
+    /** Active files in the app's collections. */
+    files: number;
+    bytes: number;
+    /** The organisation's byte cap: the tighter of its own limit and the
+     * operator ceiling. Organisation-wide, not the app's alone. `null`: none set. */
+    planBytes: number | null;
+    /** Files added since the start of this UTC month (still active). */
+    addedThisMonth: number;
+    /** Confirmed uploads in the last 7 UTC days, today included. */
+    uploadedThisWeek: number;
+    /** Downloads and share-link opens in the last 7 UTC days, today included. */
+    openedThisWeek: number;
+    /** Share links that still open. */
+    openLinks: number;
+}
+export interface AppFilesFolder {
+    /** The collection's name. Files keeps no other label. */
+    name: string;
+    files: number;
+    bytes: number;
+    lastUploadAt: string | null;
+    /** Share links that still open. */
+    links: number;
+}
+export interface AppFilesSpace {
+    /** Oldest first, at most 90. A past day appears once the daily meter has
+     * recorded it; today is always last, read live. */
+    days: {
+        day: string;
+        bytes: number;
+        uploads: number;
+    }[];
+    /** The space used at the start of `month` (`YYYY-MM`, three months on) at
+     * the average daily growth of the recorded days; `null` with fewer than
+     * 7 recorded days or no growth. */
+    forecast: {
+        bytes: number;
+        month: string;
+    } | null;
+}
+export interface AppFilesEntry {
+    id: string;
+    name: string;
+    /** The collection's name. */
+    folder: string;
+    bytes: number;
+    /** When it was added. */
+    at: string;
+}
+export interface AppFilesListQuery extends AppFilesQuery {
+    /** One of `collections`, or every one of them when absent. */
+    folder?: string | null;
+    /** Matches the file's name or its folder, case-insensitively. */
+    search?: string;
+    /** 1 to 100; 50 when absent. */
+    limit?: number;
+}
+export interface AppFilesLink {
+    id: string;
+    /** The file's name. */
+    file: string;
+    opened: number;
+    expiresAt: string | null;
+}
+/** An app's space alert (issue #164): mail `recipients` once when the
+ * bytes of the app's `collections` reach `percent` of the organisation's
+ * plan space, and again only after they drop below it and reach it again.
+ * `app` is foundry's entry key. */
+export interface SetSpaceAlertInput {
+    /** 1 to 100; absent is 80. */
+    percent?: number;
+    /** Shown in the mail; absent is the app key. */
+    name?: string;
+    /** The app's collections by name, 1 to 50. */
+    collections: string[];
+    /** The owners' addresses, at most 20. */
+    recipients: string[];
+}
+export interface SpaceAlert {
+    app: string;
+    name: string;
+    percent: number;
+    collections: string[];
+    recipients: string[];
+    /** True while the app is at or over its share, as of the last daily check. */
+    above: boolean;
+    updatedAt: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/files",
-  "version": "0.9.1",
+  "version": "0.11.1",
   "type": "module",
   "license": "MIT",
   "description": "Public client SDK and API types for the Files service.",