@knowledgefutures/sdk 0.0.0-stage → 0.1.0

package/dist/storage/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The storage interface every implementation honours: R2 behind the console,
+ * RustFS under `kf dev`, and `memoryStorage` in tests. Project code is written
+ * against these types only, and the conformance suite (conformance.ts) holds
+ * each implementation to them, so code that passes against one runs the same
+ * against the others.
+ *
+ * The surface is deliberately the subset all of them can honour: no POST
+ * policies (R2 has none), no per-object ACLs (R2 has none — public is a
+ * separate store), no multipart. Large files go browser → bucket through
+ * `signUpload`, never through the project's server.
+ */
+/** What `put` accepts. A stream is read to the end before upload; use `signUpload` for large files. */
+export type Body = string | ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array>;
+export interface PutOptions {
+    contentType?: string;
+    /** Sent back verbatim on every read — and, on the public store, what Cloudflare's cache obeys. */
+    cacheControl?: string;
+    contentDisposition?: string;
+    /** Lowercase `[a-z0-9-]` keys. Small: S3 caps all metadata at 2 KB. */
+    metadata?: Record<string, string>;
+}
+/** One object as a `list` returns it: only what every backend's listing reports. */
+export interface ListedObject {
+    key: string;
+    size: number;
+    /** Opaque. Stable while the object is unchanged; changes when it is overwritten. */
+    etag: string;
+    uploaded: Date;
+}
+/** One object as `put` and `head` report it. */
+export interface StoredObject extends ListedObject {
+    contentType: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+    metadata: Record<string, string>;
+}
+export interface ObjectBody extends StoredObject {
+    body: ReadableStream<Uint8Array>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}
+export interface ListOptions {
+    prefix?: string;
+    /** From the previous page's `cursor`. Opaque. */
+    cursor?: string;
+    /** 1–1000. Default 1000. */
+    limit?: number;
+}
+export interface ListResult {
+    /** In key order (UTF-8 byte order). */
+    objects: ListedObject[];
+    /** Present when there is another page. */
+    cursor?: string;
+}
+export interface SignUploadOptions {
+    contentType: string;
+    /** The exact byte length. It is signed, so the upload must be exactly this size. */
+    size: number;
+    /**
+     * Seconds. Default 600. Up to 604800 with fixed credentials (`kf dev`, tests);
+     * on the console, at most the storage service's credential lifetime (an hour),
+     * because a signed URL stops working when the credentials that signed it expire.
+     */
+    expiresIn?: number;
+    cacheControl?: string;
+}
+/** What a browser needs to upload: PUT the file to `url` with exactly these headers. */
+export interface SignedUpload {
+    key: string;
+    url: string;
+    method: 'PUT';
+    headers: Record<string, string>;
+    expiresAt: Date;
+}
+export interface SignDownloadOptions {
+    /** Seconds. Default 300. The same limits as `SignUploadOptions.expiresIn`. */
+    expiresIn?: number;
+    /** Served as an attachment with this file name. */
+    filename?: string;
+}
+/** A file with a name, for `upload`. A `File` is one. */
+export interface Upload {
+    body: Body;
+    contentType?: string;
+    /** Its extension carries over to the generated key. */
+    name?: string;
+}
+export interface UploadOptions {
+    /** The key is `<prefix>/<uuid><ext>`. */
+    prefix?: string;
+    cacheControl?: string;
+    metadata?: Record<string, string>;
+}
+export interface Store {
+    put(key: string, body: Body, options?: PutOptions): Promise<StoredObject>;
+    /** null when there is no such object. */
+    get(key: string): Promise<ObjectBody | null>;
+    /** null when there is no such object. */
+    head(key: string): Promise<StoredObject | null>;
+    /** Deleting what is not there is success. */
+    delete(key: string): Promise<void>;
+    list(options?: ListOptions): Promise<ListResult>;
+    signUpload(key: string, options: SignUploadOptions): Promise<SignedUpload>;
+    signDownload(key: string, options?: SignDownloadOptions): Promise<string>;
+    /** A generated key, so nothing is ever overwritten by accident. */
+    upload(file: Blob | Upload, options?: UploadOptions): Promise<StoredObject>;
+}
+/**
+ * The public store: everything in it is readable by anyone at `url(key)`,
+ * through Cloudflare's cache and with no signature. Treat its keys as
+ * immutable — an overwrite or delete is seen only after the object's
+ * `max-age`, since nothing purges the cache.
+ */
+export interface PublicStore extends Store {
+    /** Where anyone can GET the object. Synchronous: no network, no signing. */
+    url(key: string): string;
+}
+export interface Storage extends Store {
+    /** Throws `not_configured` unless the manifest declares `"public": true`. */
+    readonly public: PublicStore;
+}

package/dist/storage/types.js

@@ -0,0 +1,13 @@
+/**
+ * The storage interface every implementation honours: R2 behind the console,
+ * RustFS under `kf dev`, and `memoryStorage` in tests. Project code is written
+ * against these types only, and the conformance suite (conformance.ts) holds
+ * each implementation to them, so code that passes against one runs the same
+ * against the others.
+ *
+ * The surface is deliberately the subset all of them can honour: no POST
+ * policies (R2 has none), no per-object ACLs (R2 has none — public is a
+ * separate store), no multipart. Large files go browser → bucket through
+ * `signUpload`, never through the project's server.
+ */
+export {};

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@knowledgefutures/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Zero-config clients for Knowledge Futures platform services, configured by the console.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knowledgefutures/kf-console.git",
+    "directory": "packages/sdk"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "default": "./dist/storage/index.js"
+    },
+    "./storage/testing": {
+      "types": "./dist/storage/testing.d.ts",
+      "default": "./dist/storage/testing.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
 }