@wtfalch/files 0.10.0 → 0.11.1

package/README.md

@@ -6,7 +6,7 @@ package dependencies.
 
 ## Status
 
-Published: yes, v0.10.0, 2026-10-03.
+Published: yes, v0.11.0, 2026-10-03.
 
 ```sh
 npm install @wtfalch/files
@@ -189,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
@@ -252,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({
@@ -398,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, IssueKeyInput, IssueOrganisationKeyInput, IssuedOrganisationKey, Member, MoveFileInput, OrganisationShare, OrganisationSummary, ProvisionOrganisationInput, ProvisionOrganisationResult, QuotaSummary, RevokedOrganisationKey, 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<{
@@ -130,6 +130,18 @@ export declare function createFilesManagementClient(options: ManagementClientOpt
         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>;
@@ -145,6 +157,24 @@ 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>;

package/dist/client.js

@@ -156,6 +156,15 @@ export function createFilesManagementClient(options) {
             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
@@ -170,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`, {
@@ -184,6 +197,16 @@ 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 }),
@@ -209,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

@@ -442,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.10.0",
+  "version": "0.11.1",
   "type": "module",
   "license": "MIT",
   "description": "Public client SDK and API types for the Files service.",