@wtfalch/files 0.4.0 → 0.6.0

package/README.md

@@ -32,6 +32,22 @@ of the same operation should retain its request ID. API failures throw
 `ApiError` with `status` and `code`; the SDK does not expose raw upstream error
 bodies.
 
+Large files can go up in parts. Reserve with `multipart: true`; the reply has
+`state: 'multipart'`, `partBytes` and `partCount`, and the upload stays open for
+a day. `uploadPartUrls(uploadId, from, count)` returns presigned URLs for up to
+100 parts. PUT part n as bytes `[(n-1)*partBytes, n*partBytes)` and keep each
+response's `ETag` header. Then call `confirmUpload(uploadId, parts)` with every
+part in order. To resume, ask for fresh URLs for the parts that failed. A
+multipart file has `checksum: null`. The R2 backend supports this; the
+local-disk backend does not yet.
+
+Files can sit in folders inside a collection. Pass `path` (for example
+`reports/2026`) when you reserve an upload. `listFiles(collectionId, { path })`
+lists the files directly in that folder, and `listFolders(collectionId, path)`
+lists its subfolders. A folder exists while it holds a file, so there are no
+empty folders. A replacement keeps the file's path; moving a file is not
+supported yet.
+
 The root export provides the client and public request/response types.
 `@wtfalch/files/client` is also supported. There are no server, database,
 migration, provider-adapter or authorization-engine exports. The service
@@ -40,6 +56,17 @@ implementation is maintained in a private repository.
 The first 0.1.0 SDK targets the new service API. Production migration from Valet
 is a separate rollout; installing the SDK does not migrate accounts or files.
 
+## Migrating from `@wtfalch/storage`
+
+`@wtfalch/storage` is this same SDK under its pre-rename name (the 2026-09-20
+rename, [#26](https://github.com/wtfalch/files/pull/26)); its `dist/` is
+byte-identical to `@wtfalch/files` apart from renamed exports and the
+reference prefix. It receives no further fixes. Install `@wtfalch/files` and
+replace `createStorageClient` with `createFilesClient` (same shape). npm does
+not yet show `@wtfalch/storage` as deprecated: that requires `npm deprecate`,
+run by someone holding publish credentials for it, tracked in
+[#29](https://github.com/wtfalch/files/issues/29).
+
 ## Management integration
 
 `createFilesManagementClient` covers operator rates, organisations and audit,

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ClientOptions, type ManagementClientOptions } from './transport.js';
-import type { AuditPage, AuditQuery, BudgetSummary, CreatedShare, FilesRate, OrganisationShare, OrganisationSummary, ProvisionOrganisationInput, ProvisionOrganisationResult, QuotaSummary, SetRateInput, Share, StoredFile, UpdateOrganisationCeilingInput, UploadInput, UploadReservation, UsageDay } from './types.js';
+import type { AuditPage, AuditQuery, BudgetSummary, CreatedShare, FilesRate, OrganisationShare, OrganisationSummary, ProvisionOrganisationInput, ProvisionOrganisationResult, QuotaSummary, SetRateInput, SetWebhookResult, Share, StoredFile, UpdateOrganisationCeilingInput, UploadInput, UploadReservation, UploadedPart, UsageDay, WebhookConfig } from './types.js';
 export { ApiError, type ClientOptions, type ManagementClientOptions } from './transport.js';
 export declare function createFilesClient(options: ClientOptions): {
     createCollection: (name: string) => Promise<{
@@ -7,17 +7,34 @@ export declare function createFilesClient(options: ClientOptions): {
         name: string;
     }>;
     reserveUpload: (input: UploadInput) => Promise<UploadReservation>;
-    confirmUpload: (id: string) => Promise<StoredFile>;
+    /** A multipart upload passes the ETag of every part, in part order. */
+    confirmUpload: (id: string, parts?: UploadedPart[]) => Promise<StoredFile>;
+    /** Fresh URLs for up to 100 parts of a multipart upload, starting at
+     * part `from`. Call again to resume after a failed or expired part. */
+    uploadPartUrls: (id: string, from?: number, count?: number) => Promise<{
+        parts: {
+            partNumber: number;
+            url: string;
+        }[];
+        expiresAt: string;
+    }>;
     getFile: (id: string) => Promise<StoredFile>;
-    downloadFile: (id: string) => Promise<{
+    downloadFile: (id: string, options?: {
+        ttlSeconds?: number;
+    }) => Promise<{
         url: string;
         expiresIn: number;
     }>;
     deleteFile: (id: string) => Promise<void>;
+    /** `path` lists only the files directly in that folder. */
     listFiles: (collection: string, page?: {
         after?: string;
         limit?: number;
+        path?: string;
     }) => Promise<StoredFile[]>;
+    /** The immediate subfolders of `path` ('' is the root) that hold at least
+     * one file the caller can read. */
+    listFolders: (collection: string, path?: string) => Promise<string[]>;
     createShare: (fileId: string, expiresAt: string | null) => Promise<CreatedShare>;
     listShares: (fileId: string) => Promise<Share[]>;
     revokeShare: (shareId: string) => Promise<void>;
@@ -48,4 +65,6 @@ export declare function createFilesManagementClient(options: ManagementClientOpt
     listOrganisationShares: () => Promise<{
         shares: OrganisationShare[];
     }>;
+    getWebhook: () => Promise<WebhookConfig>;
+    setWebhook: (url: string | null) => Promise<SetWebhookResult>;
 };

package/dist/client.js

@@ -5,14 +5,26 @@ export function createFilesClient(options) {
     return {
         createCollection: (name) => call('POST', '/v1/collections', { name }),
         reserveUpload: (input) => call('POST', '/v1/uploads', input),
-        confirmUpload: (id) => call('POST', `/v1/uploads/${encodeURIComponent(id)}/confirm`),
+        /** A multipart upload passes the ETag of every part, in part order. */
+        confirmUpload: (id, parts) => call('POST', `/v1/uploads/${encodeURIComponent(id)}/confirm`, parts === undefined ? undefined : { parts }),
+        /** Fresh URLs for up to 100 parts of a multipart upload, starting at
+         * part `from`. Call again to resume after a failed or expired part. */
+        uploadPartUrls: (id, from = 1, count = 100) => call('GET', `/v1/uploads/${encodeURIComponent(id)}/parts?${new URLSearchParams({
+            from: String(from),
+            count: String(count),
+        })}`),
         getFile: (id) => call('GET', `/v1/files/${encodeURIComponent(id)}`),
-        downloadFile: (id) => call('GET', `/v1/files/${encodeURIComponent(id)}/download`),
+        downloadFile: (id, options = {}) => call('GET', `/v1/files/${encodeURIComponent(id)}/download${options.ttlSeconds === undefined ? '' : `?ttl=${options.ttlSeconds}`}`),
         deleteFile: (id) => call('DELETE', `/v1/files/${encodeURIComponent(id)}`),
+        /** `path` lists only the files directly in that folder. */
         listFiles: (collection, page = {}) => call('GET', `/v1/collections/${encodeURIComponent(collection)}/files?${new URLSearchParams({
             ...(page.after ? { after: page.after } : {}),
             ...(page.limit !== undefined ? { limit: String(page.limit) } : {}),
+            ...(page.path !== undefined ? { path: page.path } : {}),
         })}`),
+        /** The immediate subfolders of `path` ('' is the root) that hold at least
+         * one file the caller can read. */
+        listFolders: (collection, path = '') => call('GET', `/v1/collections/${encodeURIComponent(collection)}/folders?${new URLSearchParams({ path })}`).then((result) => result.folders),
         // Public share links (task S6): `files.files:share`/`files.shares:read`,
         // bearer key or signed request -- both reach the same /v1/files/*
         // routes this client already calls.
@@ -61,5 +73,8 @@ 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'),
+        // Outbound event delivery (task gap-36). setWebhook(null) disables it.
+        getWebhook: () => call('GET', '/v1/manage/webhook'),
+        setWebhook: (url) => call('PUT', '/v1/manage/webhook', { url }),
     };
 }

package/dist/types.d.ts

@@ -9,7 +9,22 @@ export interface UploadInput {
         fileId: string;
         version: number;
     };
-    retention: 'scratch' | 'durable';
+    /** 'scratch' keeps the service's own fixed default expiry; 'durable' never
+     * expires; `{ days }` is a caller-chosen expiry (1-3650 days) for a
+     * collection that wants auto-expiry on its own schedule instead of a
+     * hand-rolled cron job calling deleteFile(). A replacement upload must
+     * keep the same finite-vs-infinite category as the file it replaces, but
+     * does not reset or change an already-running expiry. */
+    retention: 'scratch' | 'durable' | {
+        days: number;
+    };
+    /** Upload in parts, resumable part by part (task gap-33). The reservation
+     * then has `state: 'multipart'`, and the upload stays open for a day. */
+    multipart?: boolean;
+    /** The folder inside the collection, e.g. `reports/2026`. Omitted or `''`
+     * is the root. '/'-separated, with no leading, trailing or empty segment.
+     * A replacement keeps the file's path. */
+    path?: string;
 }
 export interface StoredFile {
     id: string;
@@ -20,6 +35,12 @@ export interface StoredFile {
     version: number;
     collectionId: 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
+     * for a single-part upload; not present for a multipart one. */
+    checksum: string | null;
+    /** The folder inside the collection; `''` is the root. */
+    path: string;
 }
 export type UploadReservation = {
     uploadId: string;
@@ -35,7 +56,21 @@ export type UploadReservation = {
         'content-length': string;
     };
     expiresAt: string;
+} | {
+    /** Reserved with `multipart: true` (task gap-33). Get part URLs from
+     * `uploadPartUrls`, PUT part n as bytes [(n-1)*partBytes, n*partBytes),
+     * keep each response's ETag header, then `confirmUpload(id, parts)`. */
+    uploadId: string;
+    fileId: string;
+    state: 'multipart';
+    partBytes: number;
+    partCount: number;
+    expiresAt: string;
 };
+export interface UploadedPart {
+    partNumber: number;
+    etag: string;
+}
 /** Public share links (task S6). `url` is returned only from `createShare`,
  * once, and is never included in a listing -- `Share` (below) is what
  * `listShares` returns instead. */
@@ -156,6 +191,21 @@ export interface UsageDay {
     chargedMicros: string;
     rateMicrosPerGbDay: number;
 }
+/** Outbound event delivery (task gap-36): at most one endpoint per
+ * organisation, POSTed a signed `files.upload_confirmed` or
+ * `files.quota_near_ceiling` event instead of the caller polling. Delivery
+ * is best-effort with no retry queue -- a receiver must be idempotent. */
+export interface WebhookConfig {
+    url: string | null;
+}
+export interface SetWebhookResult extends WebhookConfig {
+    /** Present only in `setWebhook()`'s own response, and only when a url was
+     * set -- `getWebhook()` never returns it. Generated fresh on every
+     * successful set; this is the rotation mechanism. Verify a delivery's
+     * `x-files-webhook-signature: sha256=<hex hmac-sha256 of the raw body>`
+     * header with it. */
+    secret: string | null;
+}
 /** Operator audit filters. Omitted dates select the most recent 92 days. */
 export interface AuditQuery {
     organisation?: string;

package/package.json

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