@wtfalch/files 0.5.0 → 0.7.0

package/README.md

@@ -41,6 +41,16 @@ 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.
 
+`getFile(id, version)` and `downloadFile(id, { version })` pin the read to an
+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
+`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).
+
 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)`
@@ -48,6 +58,15 @@ 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.
 
+Image files can be resized on demand instead of a tenant running its own
+thumbnail pipeline: `getFileVariant(fileId, width, format)` returns a signed
+URL to a resized, re-encoded copy, built with `sharp` on first request and
+served from a stored copy on every one after. `width` must be one of
+`VARIANT_WIDTHS` (64, 256 or 1024); `format` is `'webp'` or `'jpeg'`. Only a
+file whose content type `sharp` can decode (JPEG, PNG, WebP, GIF, AVIF)
+qualifies -- anything else answers `invalid_request`. A variant's bytes count
+against the same byte quota an upload does.
+
 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

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, SetWebhookResult, Share, StoredFile, UpdateOrganisationCeilingInput, UploadInput, UploadReservation, UploadedPart, UsageDay, WebhookConfig } from './types.js';
+import type { AuditPage, AuditQuery, BudgetSummary, CreatedShare, FilesRate, OrganisationShare, OrganisationSummary, ProvisionOrganisationInput, ProvisionOrganisationResult, QuotaSummary, SetRateInput, SetWebhookResult, Share, 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<{
@@ -18,13 +18,24 @@ export declare function createFilesClient(options: ClientOptions): {
         }[];
         expiresAt: string;
     }>;
-    getFile: (id: string) => Promise<StoredFile>;
+    /** `version`, when given, pins the read to that exact file version:
+     * `ApiError` with `status: 409` if the file has since moved on. */
+    getFile: (id: string, version?: number) => Promise<StoredFile>;
+    /** `version`, when given, pins the download to that exact file version,
+     * same as `getFile` -- only the current version's bytes exist in the
+     * backend at all, so a mismatch is always a 409, never a historical
+     * read. */
     downloadFile: (id: string, options?: {
         ttlSeconds?: number;
+        version?: number;
     }) => Promise<{
         url: string;
         expiresIn: number;
     }>;
+    getFileVariant: (id: string, width: VariantWidth, format: VariantFormat) => Promise<{
+        url: string;
+        expiresIn: number;
+    }>;
     deleteFile: (id: string) => Promise<void>;
     /** `path` lists only the files directly in that folder. */
     listFiles: (collection: string, page?: {

package/dist/client.js

@@ -13,8 +13,26 @@ export function createFilesClient(options) {
             from: String(from),
             count: String(count),
         })}`),
-        getFile: (id) => call('GET', `/v1/files/${encodeURIComponent(id)}`),
-        downloadFile: (id, options = {}) => call('GET', `/v1/files/${encodeURIComponent(id)}/download${options.ttlSeconds === undefined ? '' : `?ttl=${options.ttlSeconds}`}`),
+        /** `version`, when given, pins the read to that exact file version:
+         * `ApiError` with `status: 409` if the file has since moved on. */
+        getFile: (id, version) => call('GET', `/v1/files/${encodeURIComponent(id)}${version === undefined ? '' : `?version=${version}`}`),
+        /** `version`, when given, pins the download to that exact file version,
+         * same as `getFile` -- only the current version's bytes exist in the
+         * backend at all, so a mismatch is always a 409, never a historical
+         * read. */
+        downloadFile: (id, options = {}) => {
+            const params = new URLSearchParams();
+            if (options.ttlSeconds !== undefined)
+                params.set('ttl', String(options.ttlSeconds));
+            if (options.version !== undefined)
+                params.set('version', String(options.version));
+            const query = params.toString();
+            return call('GET', `/v1/files/${encodeURIComponent(id)}/download${query ? `?${query}` : ''}`);
+        },
+        // Lazily generated image variants (task gap-32): created on first
+        // request, served from a stored copy on every one after. `width` must be
+        // one of `VARIANT_WIDTHS`; the service answers 400 otherwise.
+        getFileVariant: (id, width, format) => call('GET', `/v1/files/${encodeURIComponent(id)}/variants/${width}.${format}`),
         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({

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './client.js';
 export type * from './types.js';
+export { VARIANT_WIDTHS } from './types.js';
 export { fileReference, fileIdFromReference } from './references.js';

package/dist/index.js

@@ -1,2 +1,4 @@
 export * from './client.js';
+// A runtime value, not a type -- `export type *` above does not re-export it.
+export { VARIANT_WIDTHS } from './types.js';
 export { fileReference, fileIdFromReference } from './references.js';

package/dist/types.d.ts

@@ -39,9 +39,27 @@ export interface StoredFile {
      * 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;
+    /** `"sha256:<hex>"` of the confirmed bytes, computed directly from the
+     * bytes rather than derived from a backend etag. `null` when the storage
+     * backend exposed no byte access at confirm time, or for a file confirmed
+     * before this field existed. */
+    sha256: string | null;
     /** The folder inside the collection; `''` is the root. */
     path: string;
+    /** The principal (e.g. `"agent:ai-service"` or `"human:alice"`) whose
+     * upload confirmed this file at its current version, when that upload is
+     * still on record. `null` for a file at version 0 (never confirmed), or
+     * when the confirming upload can no longer be found. */
+    principalRef: string | null;
 }
+/** Lazily generated image variants (task gap-32), served through
+ * `getFileVariant`. A fixed allowlist -- not an arbitrary size -- so a
+ * caller cannot mint an unbounded number of billable objects per file.
+ * Variant bytes count against the same organisation (and key) byte quota an
+ * upload does. */
+export declare const VARIANT_WIDTHS: readonly [64, 256, 1024];
+export type VariantWidth = (typeof VARIANT_WIDTHS)[number];
+export type VariantFormat = 'webp' | 'jpeg';
 export type UploadReservation = {
     uploadId: string;
     fileId: string;

package/dist/types.js

@@ -1 +1,6 @@
-export {};
+/** Lazily generated image variants (task gap-32), served through
+ * `getFileVariant`. A fixed allowlist -- not an arbitrary size -- so a
+ * caller cannot mint an unbounded number of billable objects per file.
+ * Variant bytes count against the same organisation (and key) byte quota an
+ * upload does. */
+export const VARIANT_WIDTHS = [64, 256, 1024];

package/package.json

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