@contract-kit/provider-storage-s3 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# @contract-kit/provider-storage-s3
+
+## 1.0.0
+
+### Minor Changes
+
+- 408ceb9: Add an S3-compatible storage provider with `createS3Storage`,
+  `createS3StorageProvider`, and `s3StorageProvider` for AWS S3, Cloudflare R2,
+  MinIO, and similar object stores.
+
+### Patch Changes
+
+- Updated dependencies [55f651c]
+- Updated dependencies [e73a554]
+- Updated dependencies [481e8ca]
+- Updated dependencies [58d5528]
+- Updated dependencies [c8b51ea]
+- Updated dependencies [c5829fb]
+- Updated dependencies [56ac09f]
+- Updated dependencies [01eccbc]
+  - @contract-kit/devtools@1.0.0
+  - @contract-kit/ports@1.0.0
+
+## 0.1.10
+
+### Patch Changes
+
+- Initial S3-compatible storage provider package.

package/README.md

@@ -0,0 +1,141 @@
+# @contract-kit/provider-storage-s3
+
+S3-compatible object storage provider for Contract Kit.
+
+The provider installs the app-facing `ctx.ports.storage` port. Use it for
+production object storage on AWS S3, Cloudflare R2, MinIO, Backblaze B2,
+DigitalOcean Spaces, or another S3-compatible backend.
+
+## Install
+
+```bash
+bun add @contract-kit/provider-storage-s3
+```
+
+## Provider setup
+
+```typescript
+import { s3StorageProvider } from "@contract-kit/provider-storage-s3";
+import { createServer } from "@contract-kit/server";
+
+const server = await createServer({
+  ports: basePorts,
+  providers: [s3StorageProvider],
+  createContext: ({ ports }) => ({ ports }),
+  routes,
+});
+```
+
+Environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `STORAGE_S3_BUCKET` | Bucket name. |
+| `STORAGE_S3_REGION` | Region. Defaults to `us-east-1`. Use `auto` for Cloudflare R2. |
+| `STORAGE_S3_ENDPOINT` | Optional S3-compatible endpoint. Required for R2, MinIO, Spaces, B2, and similar services. |
+| `STORAGE_S3_ACCESS_KEY_ID` | Optional static access key. |
+| `STORAGE_S3_SECRET_ACCESS_KEY` | Optional static secret key. |
+| `STORAGE_S3_SESSION_TOKEN` | Optional static session token. |
+| `STORAGE_S3_PUBLIC_BASE_URL` | Optional base URL returned by `publicUrl(...)` for public objects. |
+| `STORAGE_S3_FORCE_PATH_STYLE` | Optional `true` or `false` path-style addressing toggle. |
+| `STORAGE_S3_KEY_PREFIX` | Optional prefix for every object key written by this app. |
+
+## AWS S3
+
+```bash
+STORAGE_S3_BUCKET=my-app-assets
+STORAGE_S3_REGION=us-east-1
+STORAGE_S3_PUBLIC_BASE_URL=https://cdn.example.com
+```
+
+When credentials are omitted, the AWS SDK uses its normal credential provider
+chain.
+
+## Cloudflare R2
+
+```bash
+STORAGE_S3_BUCKET=my-app-assets
+STORAGE_S3_REGION=auto
+STORAGE_S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+STORAGE_S3_ACCESS_KEY_ID=...
+STORAGE_S3_SECRET_ACCESS_KEY=...
+STORAGE_S3_PUBLIC_BASE_URL=https://assets.example.com
+```
+
+R2 is S3-compatible, but not every S3 feature exists on every compatible
+service. This provider only relies on object `put`, `get`, `head`, and
+`delete`.
+
+## Direct port factory
+
+```typescript
+import { createS3Storage } from "@contract-kit/provider-storage-s3";
+
+const storage = createS3Storage({
+  bucket: "my-app-assets",
+  region: "auto",
+  endpoint: "https://<account-id>.r2.cloudflarestorage.com",
+  credentials: {
+    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+  },
+  publicBaseUrl: "https://assets.example.com",
+});
+```
+
+The same `StoragePort` works with local files, memory tests, and
+S3-compatible object stores:
+
+```typescript
+await ctx.ports.storage.put("avatars/user_123.png", avatarBytes, {
+  contentType: "image/png",
+  visibility: "public",
+});
+
+const object = await ctx.ports.storage.get("avatars/user_123.png");
+const url = await ctx.ports.storage.publicUrl("avatars/user_123.png");
+```
+
+## Visibility
+
+`visibility` is stored as reserved object metadata so `publicUrl(...)` can
+return URLs only for objects written with `visibility: "public"`. The provider
+does not set S3 ACLs. Configure bucket policies, R2 public buckets, or a CDN
+outside the provider when objects should be publicly reachable.
+
+The reserved metadata key is `ck-visibility`. It is hidden from
+`StorageObject.metadata`.
+
+## Escape hatch
+
+The provider also installs `ctx.ports.s3Storage` for S3-specific operations that
+do not belong in `StoragePort`:
+
+```typescript
+import { ListObjectsV2Command } from "@aws-sdk/client-s3";
+
+const s3Key = ctx.ports.s3Storage.objectKey("exports/report.csv");
+const s3Prefix = ctx.ports.s3Storage.objectPrefix("exports");
+
+await ctx.ports.s3Storage.client.send(
+  new ListObjectsV2Command({
+    Bucket: ctx.ports.s3Storage.bucket,
+    Prefix: s3Prefix,
+  }),
+);
+```
+
+Use `objectKey(...)` when direct S3 calls need to address objects written
+through `ctx.ports.storage`. Use `objectPrefix(...)` for list operations. Both
+helpers apply the configured `STORAGE_S3_KEY_PREFIX`.
+
+## Devtools
+
+When `ctx.ports.devtools` is installed, the provider records storage
+operations under the `storage` watcher. Events include operation name, key,
+bucket, duration, object size, visibility, and whether a lookup hit. Object
+bodies and metadata values are never recorded.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+import { S3Client, type S3ClientConfig } from "@aws-sdk/client-s3";
+import { type StoragePort } from "@contract-kit/ports";
+import { z } from "zod";
+export type { StorageBody, StorageMetadata, StorageObject, StorageObjectBody, StoragePort, StorageVisibility, } from "@contract-kit/ports";
+declare const S3StorageConfigSchema: z.ZodObject<{
+    BUCKET: z.ZodString;
+    REGION: z.ZodDefault<z.ZodString>;
+    ENDPOINT: z.ZodOptional<z.ZodString>;
+    ACCESS_KEY_ID: z.ZodOptional<z.ZodString>;
+    SECRET_ACCESS_KEY: z.ZodOptional<z.ZodString>;
+    SESSION_TOKEN: z.ZodOptional<z.ZodString>;
+    PUBLIC_BASE_URL: z.ZodOptional<z.ZodString>;
+    FORCE_PATH_STYLE: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "true" | "false">>>;
+    KEY_PREFIX: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type S3StorageConfig = z.infer<typeof S3StorageConfigSchema>;
+export type S3StorageClient = Pick<S3Client, "send">;
+export interface S3StorageOptions {
+    /**
+     * S3 bucket name.
+     */
+    bucket: string;
+    /**
+     * S3-compatible client. Omit to create an AWS SDK S3Client from config.
+     */
+    client?: S3StorageClient;
+    /**
+     * Region used when creating the default S3Client.
+     *
+     * @default "us-east-1"
+     */
+    region?: string;
+    /**
+     * S3-compatible endpoint. Required for R2, MinIO, Spaces, B2, and most
+     * non-AWS object stores.
+     */
+    endpoint?: string;
+    /**
+     * Static credentials used when creating the default S3Client.
+     */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    /**
+     * Use path-style bucket addressing when required by the object store.
+     */
+    forcePathStyle?: boolean;
+    /**
+     * Prefix all object keys before sending them to S3.
+     */
+    keyPrefix?: string;
+    /**
+     * Base URL used by `publicUrl(...)` for public objects.
+     */
+    publicBaseUrl?: string;
+    /**
+     * Additional AWS SDK S3Client config.
+     */
+    clientConfig?: Omit<S3ClientConfig, "region" | "endpoint" | "credentials" | "forcePathStyle">;
+    /**
+     * Optional devtools target. The provider passes existing app ports here
+     * automatically; direct factory users can pass a devtools port explicitly.
+     */
+    devtools?: unknown;
+}
+export interface S3StorageProviderOptions extends Omit<S3StorageOptions, "bucket" | "client" | "devtools"> {
+    /**
+     * Provider name. Defaults to "storage-s3".
+     */
+    name?: string;
+    /**
+     * Default bucket used when STORAGE_S3_BUCKET is not set.
+     */
+    bucket?: string;
+    /**
+     * Optional client factory for tests or custom S3 clients.
+     */
+    createClient?: (config: S3StorageConfig) => S3StorageClient;
+}
+export declare function createS3Storage(options: S3StorageOptions): StoragePort;
+export interface S3StorageProviderPorts {
+    storage: StoragePort;
+    s3Storage: {
+        client: S3StorageClient;
+        bucket: string;
+        keyPrefix: string;
+        objectKey(key: string): string;
+        objectPrefix(prefix: string): string;
+    };
+}
+export declare function createS3StorageProvider(options?: S3StorageProviderOptions): import("@contract-kit/ports").ServiceProvider<unknown, z.ZodObject<{
+    ACCESS_KEY_ID: z.ZodOptional<z.ZodString>;
+    SECRET_ACCESS_KEY: z.ZodOptional<z.ZodString>;
+    SESSION_TOKEN: z.ZodOptional<z.ZodString>;
+    BUCKET: z.ZodString | z.ZodDefault<z.ZodString>;
+    REGION: z.ZodDefault<z.ZodString>;
+    ENDPOINT: z.ZodDefault<z.ZodString> | z.ZodOptional<z.ZodString>;
+    PUBLIC_BASE_URL: z.ZodDefault<z.ZodString> | z.ZodOptional<z.ZodString>;
+    FORCE_PATH_STYLE: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "true" | "false">>> | z.ZodDefault<z.ZodPipe<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "true" | "false">>>;
+    KEY_PREFIX: z.ZodDefault<z.ZodString> | z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, {
+    storage: StoragePort;
+    s3Storage: {
+        client: S3StorageClient;
+        bucket: string;
+        keyPrefix: string;
+        objectKey(key: string): string;
+        objectPrefix(prefix: string): string;
+    };
+}>;
+export declare const s3StorageProvider: import("@contract-kit/ports").ServiceProvider<unknown, z.ZodObject<{
+    ACCESS_KEY_ID: z.ZodOptional<z.ZodString>;
+    SECRET_ACCESS_KEY: z.ZodOptional<z.ZodString>;
+    SESSION_TOKEN: z.ZodOptional<z.ZodString>;
+    BUCKET: z.ZodString | z.ZodDefault<z.ZodString>;
+    REGION: z.ZodDefault<z.ZodString>;
+    ENDPOINT: z.ZodDefault<z.ZodString> | z.ZodOptional<z.ZodString>;
+    PUBLIC_BASE_URL: z.ZodDefault<z.ZodString> | z.ZodOptional<z.ZodString>;
+    FORCE_PATH_STYLE: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "true" | "false">>> | z.ZodDefault<z.ZodPipe<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "true" | "false">>>;
+    KEY_PREFIX: z.ZodDefault<z.ZodString> | z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, {
+    storage: StoragePort;
+    s3Storage: {
+        client: S3StorageClient;
+        bucket: string;
+        keyPrefix: string;
+        objectKey(key: string): string;
+        objectPrefix(prefix: string): string;
+    };
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,QAAQ,EACR,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAML,KAAK,WAAW,EAEjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,YAAY,EACV,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAQ7B,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;iBAUzB,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IAEzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,WAAW,CAAC,EAAE;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IAEF;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,YAAY,CAAC,EAAE,IAAI,CACjB,cAAc,EACd,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,gBAAgB,CACzD,CAAC;IAEF;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBACf,SAAQ,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;IAChE;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,eAAe,CAAC;CAC7D;AAuWD,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,WAAW,CAgTtE;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE;QACT,MAAM,EAAE,eAAe,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;QAC/B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;KACtC,CAAC;CACH;AAED,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,wBAA6B;;;;;;;;;;;;;;;;;;;;;;;;;GA+FvC;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;EAA4B,CAAC"}