@cosmicdrift/kumiko-types 0.159.0 → 0.160.0

package/src/file-handle-types.ts

@@ -0,0 +1,19 @@
+export type FileHandle = {
+  readonly key: string;
+  read(): Promise<Uint8Array>;
+  write(data: Uint8Array, mimeType?: string): Promise<void>;
+  delete(): Promise<void>;
+  exists(): Promise<boolean>;
+  // Produce a handle for a derived key (e.g. a thumbnail). Does not touch
+  // storage; only computes the key. Writing to the derived handle is the
+  // caller's job.
+  derive(suffix: string): FileHandle;
+};
+
+// The `ctx.files` service — a factory that materialises a FileHandle for a
+// storage key. One per request/event, bound to a single tenant: the provider
+// is resolved per-tenant through file-foundation, so uploads, ctx.files and the
+// GDPR jobs all hit the same store by construction.
+export type FileContext = {
+  ref(key: string): FileHandle;
+};

package/src/file-provider-resolver-types.ts

@@ -0,0 +1,7 @@
+import type { FileStorageProvider } from "./file-storage-provider-types";
+import type { TenantId } from "./identifiers";
+
+// A bound, per-tenant provider resolver. One instance serves all tenants
+// (tenantId is the call argument) — the single spine shared by upload routes,
+// ctx.files and the GDPR jobs.
+export type FileProviderResolver = (tenantId: TenantId) => Promise<FileStorageProvider>;

package/src/file-storage-provider-types.ts

@@ -0,0 +1,39 @@
+// Options for `getSignedUrl`. `contentDisposition` lets the caller hint the
+// browser to download-with-name vs inline-display (maps to ResponseContent-
+// Disposition on S3). Keep the option-bag small and additive; provider impls
+// that don't support a given hint should ignore it rather than error.
+export type SignedUrlOptions = {
+  readonly contentDisposition?: string;
+};
+
+// Options for `writeStream`. `mimeType` is a Content-Type hint analogous to
+// `write`. `contentLength` is optional for providers that need a Length
+// header (S3 multipart has a TransferManager and can work without it);
+// local providers ignore both.
+export type WriteStreamOptions = {
+  readonly mimeType?: string;
+  readonly contentLength?: number;
+};
+
+// Primitive storage contract: key+bytes in, bytes out. Metadata (fileName,
+// mimeType, size) lives on the FileRef row — the provider only needs to
+// shuttle bytes. `mimeType` on write() is a hint for providers that need a
+// Content-Type header (S3/R2/…); local filesystems can ignore it.
+//
+// getSignedUrl is optional — providers without native presigned-URL support
+// (filesystem) leave it undefined; the route then returns 501 and the
+// client falls back to streaming via GET /files/:id. Callers must
+// feature-detect via `typeof provider.getSignedUrl === "function"`.
+export type FileStorageProvider = {
+  write(key: string, data: Uint8Array, mimeType?: string): Promise<void>;
+  writeStream(
+    key: string,
+    source: AsyncIterable<Uint8Array>,
+    options?: WriteStreamOptions,
+  ): Promise<void>;
+  read(key: string): Promise<Uint8Array>;
+  readStream(key: string): AsyncIterable<Uint8Array>;
+  delete(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  getSignedUrl?(key: string, expiresInSeconds: number, options?: SignedUrlOptions): Promise<string>;
+};