@wtfalch/files 0.9.1 → 0.10.0

package/README.md

@@ -6,7 +6,7 @@ package dependencies.
 
 ## Status
 
-Published: yes, v0.9.1, 2026-09-28.
+Published: yes, v0.10.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).

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, 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';
 export { ApiError, type ClientOptions, type ManagementClientOptions } from './transport.js';
 export declare function createFilesClient(options: ClientOptions): {
     createCollection: (name: string) => Promise<{
@@ -122,6 +122,14 @@ 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;
+    }>;
     updateOrganisationCeiling: (organisationId: string, input: UpdateOrganisationCeilingInput) => Promise<OrganisationSummary>;
     deleteOrganisation: (organisationId: string) => Promise<OrganisationSummary>;
     restoreOrganisation: (organisationId: string) => Promise<OrganisationSummary>;
@@ -139,6 +147,8 @@ export declare function createFilesManagementClient(options: ManagementClientOpt
     }>;
     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,23 @@ 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 };
+        },
         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 +187,14 @@ export function createFilesManagementClient(options) {
         // 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

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;

package/package.json

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