@contract-kit/provider-storage-local 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# @contract-kit/provider-storage-local
+
+## 1.0.0
+
+### Minor Changes
+
+- 72d66cb: Add a local filesystem storage provider with `createLocalStorage`,
+  `createLocalStorageProvider`, and `localStorageProvider`. Add
+  `createStorageRoute` for serving public storage objects from Next.js apps and
+  wire local storage into the framework starter.
+
+### 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 local filesystem storage provider package.

package/README.md

@@ -0,0 +1,94 @@
+# @contract-kit/provider-storage-local
+
+Local filesystem storage provider for Contract Kit.
+
+The provider installs the app-facing `ctx.ports.storage` port. Use it for
+local development, tests that need durable files, and small deployments where a
+filesystem-backed object store is enough.
+
+## Install
+
+```bash
+bun add @contract-kit/provider-storage-local
+```
+
+## Provider setup
+
+```typescript
+import { localStorageProvider } from "@contract-kit/provider-storage-local";
+import { createServer } from "@contract-kit/server";
+
+const server = await createServer({
+  ports: basePorts,
+  providers: [localStorageProvider],
+  createContext: ({ ports }) => ({ ports }),
+  routes,
+});
+```
+
+Environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `STORAGE_ROOT` | Directory where objects are written. Defaults to `storage/app`. |
+| `STORAGE_PUBLIC_BASE_URL` | Optional base URL returned by `publicUrl(...)` for public objects. |
+
+`STORAGE_PUBLIC_BASE_URL` may be an absolute URL such as
+`https://assets.example.com` or an app-relative path such as `/storage`.
+The provider only returns URLs. If you use an app-relative path in a Next.js
+app, serve public objects with `createStorageRoute`:
+
+```typescript
+// app/storage/[...key]/route.ts
+import { createStorageRoute } from "@contract-kit/next";
+import { server } from "@/server";
+
+export const { GET, HEAD } = createStorageRoute(server.ports.storage, {
+  basePath: "/storage",
+});
+```
+
+## Direct port factory
+
+```typescript
+import { createLocalStorage } from "@contract-kit/provider-storage-local";
+
+const storage = createLocalStorage({
+  root: "storage/app",
+  publicBaseUrl: "/storage",
+});
+```
+
+The same `StoragePort` works with local files, memory tests, and cloud 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");
+```
+
+## Files on disk
+
+Objects are written below `root` using their storage key. Object metadata is
+stored in a `.ck-storage-meta` sidecar directory below the same root.
+
+Storage keys must be relative object keys: no empty strings, empty path
+segments, leading or trailing `/`, backslashes, or `.` / `..` path segments.
+The `.ck-storage-meta` path segment is reserved for the provider's sidecar
+metadata.
+
+## Devtools
+
+When `ctx.ports.devtools` is installed, the provider records storage
+operations under the `storage` watcher. Events include operation name, key,
+duration, object size, visibility, and whether a lookup hit. Object bodies are
+never recorded.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+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 LocalStorageConfigSchema: z.ZodObject<{
+    ROOT: z.ZodDefault<z.ZodString>;
+    PUBLIC_BASE_URL: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LocalStorageConfig = z.infer<typeof LocalStorageConfigSchema>;
+export interface LocalStorageOptions {
+    /**
+     * Directory where storage objects are written.
+     */
+    root: string;
+    /**
+     * Base URL used by `publicUrl(...)` for public objects.
+     */
+    publicBaseUrl?: string;
+    /**
+     * Optional devtools target. The provider passes existing app ports here
+     * automatically; direct factory users can pass a devtools port explicitly.
+     */
+    devtools?: unknown;
+}
+export interface LocalStorageProviderOptions {
+    /**
+     * Provider name. Defaults to "storage-local".
+     */
+    name?: string;
+    /**
+     * Default root used when STORAGE_ROOT is not set.
+     */
+    root?: string;
+    /**
+     * Default public base URL used when STORAGE_PUBLIC_BASE_URL is not set.
+     */
+    publicBaseUrl?: string;
+}
+export declare function createLocalStorage(options: LocalStorageOptions): StoragePort;
+export interface LocalStorageProviderPorts {
+    storage: StoragePort;
+}
+export declare function createLocalStorageProvider(options?: LocalStorageProviderOptions): import("@contract-kit/ports").ServiceProvider<unknown, z.ZodObject<{
+    PUBLIC_BASE_URL: z.ZodOptional<z.ZodString>;
+    ROOT: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, {
+    storage: StoragePort;
+}>;
+export declare const localStorageProvider: import("@contract-kit/ports").ServiceProvider<unknown, z.ZodObject<{
+    PUBLIC_BASE_URL: z.ZodOptional<z.ZodString>;
+    ROOT: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, {
+    storage: StoragePort;
+}>;
+//# 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,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;AAI7B,QAAA,MAAM,wBAAwB;;;iBAG5B,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA8UD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,WAAW,CAyQ5E;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,2BAAgC;;;;;GAoC1C;AAED,eAAO,MAAM,oBAAoB;;;;;EAA+B,CAAC"}