@storyshelf/storage-gcs 0.0.0-stage → 0.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @storyshelf/storage-gcs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Google Cloud Storage (GCS) adapter for StoryShelf: reads and writes blobs to a GCS bucket, including GCS-compatible emulators.
+
+## Install
+
+```sh
+nub add @storyshelf/storage-gcs
+```
+
+or
+
+```sh
+npm install @storyshelf/storage-gcs
+```
+
+## Quick start
+
+```ts
+import { createGcsStorage } from "@storyshelf/storage-gcs";
+import { createShelfApp } from "@storyshelf/app";
+
+const storage = createGcsStorage({
+  bucket: "my-shelf",
+  prefix: "storyshelf", // optional
+  projectId: "my-gcp-project", // optional, defaults to ADC
+});
+
+const app = createShelfApp({ database, storage });
+```
+
+For local emulators or custom endpoints:
+
+```ts
+const storage = createGcsStorage({
+  bucket: "my-shelf",
+  apiEndpoint: "http://localhost:9090",
+  projectId: "test-project",
+});
+```
+
+Inject a pre-configured client (tests / IAM-rotation):
+
+```ts
+import { Storage } from "@google-cloud/storage";
+
+const client = new Storage({ projectId: "my-project" });
+const storage = createGcsStorage({ bucket: "my-shelf", client });
+```
+
+## API
+
+### `GcsStorageOptions`
+
+```ts
+interface GcsStorageOptions {
+  bucket: string; // required GCS bucket name
+  prefix?: string; // optional key prefix, defaults to ""
+  client?: Storage; // optional pre-configured @google-cloud/storage client
+  projectId?: string; // optional GCP project id
+  keyFilename?: string; // optional path to service-account JSON
+  credentials?: object; // optional service-account credentials object
+  apiEndpoint?: string; // optional custom endpoint (emulator)
+}
+```
+
+### `createGcsStorage(options: GcsStorageOptions): StorageAdapter`
+
+Creates a `StorageAdapter` backed by the configured GCS bucket. The returned adapter implements every method of the `StorageAdapter` interface (`read`, `write`, `delete`, `exists`, `list(prefix)`, `readStream`, `writeStream`).
+
+### `gcsKey(prefix: string, path: string): string`
+
+Helper that joins a storage prefix with a relative path into an object key.
+
+## How it fits in
+
+`storage-gcs` is the `storage` option for `createShelfApp` in GCP deployments. It implements the same `StorageAdapter` interface as `@storyshelf/storage-local` and `@storyshelf/storage-s3`, so switching between local disk, S3, and GCS requires no changes elsewhere.
+
+See `docs/architecture.md` and ADR 0006.

package/dist/client.mjs

@@ -0,0 +1,27 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { Storage } from "@google-cloud/storage";
+//#region src/client.ts
+/** GCS Storage client construction and shared operation context. */
+/** Build the bucket handle plus key prefix every GCS operation threads through. */
+function createGcsContext(options) {
+	const { bucket: bucketName, prefix = "", client: injectedClient } = options;
+	return {
+		bucket: (injectedClient ?? new Storage(resolveClientOptions(options))).bucket(bucketName),
+		prefix
+	};
+}
+/** Translate adapter options into @google-cloud/storage constructor options. */
+function resolveClientOptions(options) {
+	const config = {};
+	if (options.projectId !== void 0) config.projectId = options.projectId;
+	if (options.keyFilename !== void 0) config.keyFilename = options.keyFilename;
+	if (options.credentials !== void 0) config.credentials = options.credentials;
+	if (options.apiEndpoint !== void 0) config.apiEndpoint = options.apiEndpoint;
+	return config;
+}
+//#endregion
+export { createGcsContext, resolveClientOptions };
+
+//# sourceMappingURL=client.mjs.map

package/dist/client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.mjs","names":[],"sources":["../src/client.ts"],"sourcesContent":["/** GCS Storage client construction and shared operation context. */\nimport { Storage } from \"@google-cloud/storage\";\nimport type { GcsStorageOptions } from \"./types.ts\";\n\n/** Build the bucket handle plus key prefix every GCS operation threads through. */\nexport function createGcsContext(options: GcsStorageOptions): GcsContext {\n  const { bucket: bucketName, prefix = \"\", client: injectedClient } = options;\n  const client = injectedClient ?? new Storage(resolveClientOptions(options));\n  return { bucket: client.bucket(bucketName), prefix };\n}\n\n/** Shared GCS bucket handle plus key prefix. */\nexport interface GcsContext {\n  bucket: ReturnType<Storage[\"bucket\"]>;\n  prefix: string;\n}\n\n/** Translate adapter options into @google-cloud/storage constructor options. */\nexport function resolveClientOptions(\n  options: GcsStorageOptions,\n): ConstructorParameters<typeof Storage>[0] {\n  const config: ConstructorParameters<typeof Storage>[0] = {};\n  if (options.projectId !== undefined) {\n    config.projectId = options.projectId;\n  }\n  if (options.keyFilename !== undefined) {\n    config.keyFilename = options.keyFilename;\n  }\n  if (options.credentials !== undefined) {\n    config.credentials = options.credentials;\n  }\n  if (options.apiEndpoint !== undefined) {\n    config.apiEndpoint = options.apiEndpoint;\n  }\n  return config;\n}\n"],"mappings":";;;;;;;AAKA,SAAgB,iBAAiB,SAAwC;CACvE,MAAM,EAAE,QAAQ,YAAY,SAAS,IAAI,QAAQ,mBAAmB;CAEpE,OAAO;EAAE,SADM,kBAAkB,IAAI,QAAQ,qBAAqB,OAAO,CAAC,EAAA,CAClD,OAAO,UAAU;EAAG;CAAO;AACrD;;AASA,SAAgB,qBACd,SAC0C;CAC1C,MAAM,SAAmD,CAAC;CAC1D,IAAI,QAAQ,cAAc,KAAA,GACxB,OAAO,YAAY,QAAQ;CAE7B,IAAI,QAAQ,gBAAgB,KAAA,GAC1B,OAAO,cAAc,QAAQ;CAE/B,IAAI,QAAQ,gBAAgB,KAAA,GAC1B,OAAO,cAAc,QAAQ;CAE/B,IAAI,QAAQ,gBAAgB,KAAA,GAC1B,OAAO,cAAc,QAAQ;CAE/B,OAAO;AACT"}

package/dist/errors.mjs

@@ -0,0 +1,16 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/errors.ts
+/** Not-found guard for GCS API errors. */
+/** Return whether a GCS error signals a missing object. */
+function isNotFound(error) {
+	const err = error;
+	if (err.code === 404 || err.code === "404" || err.code === "notFound") return true;
+	if (err.statusCode === 404) return true;
+	return err.errors?.[0]?.reason === "notFound";
+}
+//#endregion
+export { isNotFound };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/** Not-found guard for GCS API errors. */\n\n/** Return whether a GCS error signals a missing object. */\nexport function isNotFound(error: unknown): boolean {\n  const err = error as {\n    code?: number | string;\n    statusCode?: number;\n    errors?: { reason?: string }[];\n  };\n  if (err.code === 404 || err.code === \"404\" || err.code === \"notFound\") {\n    return true;\n  }\n  if (err.statusCode === 404) {\n    return true;\n  }\n  return err.errors?.[0]?.reason === \"notFound\";\n}\n"],"mappings":";;;;;;AAGA,SAAgB,WAAW,OAAyB;CAClD,MAAM,MAAM;CAKZ,IAAI,IAAI,SAAS,OAAO,IAAI,SAAS,SAAS,IAAI,SAAS,YACzD,OAAO;CAET,IAAI,IAAI,eAAe,KACrB,OAAO;CAET,OAAO,IAAI,SAAS,EAAE,EAAE,WAAW;AACrC"}

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { GcsStorageOptions } from "./types.mjs";
+import { gcsKey } from "./keys.mjs";
+import { StorageAdapter } from "@storyshelf/core/adapter/storage";
+//#region src/index.d.ts
+/**
+ * Create a Google Cloud Storage (GCS) StorageAdapter.
+ *
+ * @param options - GCS configuration options.
+ * @returns A StorageAdapter backed by the configured GCS bucket.
+ */
+declare function createGcsStorage(options: GcsStorageOptions): StorageAdapter;
+//#endregion
+export { type GcsStorageOptions, createGcsStorage, gcsKey };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,53 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { createGcsContext } from "./client.mjs";
+import { createGcsLifecycle } from "./lifecycle.mjs";
+import { gcsKey } from "./keys.mjs";
+import { gcsDelete, gcsExists, gcsList, gcsRead, gcsWrite } from "./operations.mjs";
+import { gcsReadStream, gcsWriteStream } from "./streams.mjs";
+//#region src/index.ts
+/**
+* Create a Google Cloud Storage (GCS) StorageAdapter.
+*
+* @param options - GCS configuration options.
+* @returns A StorageAdapter backed by the configured GCS bucket.
+*/
+function createGcsStorage(options) {
+	const ctx = createGcsContext(options);
+	return {
+		metadata: {
+			name: "GCS Storage",
+			version: globalThis.__PKG_VERSION__ ?? "0.0.0",
+			description: "Google Cloud Storage adapter",
+			kind: "gcs",
+			category: "storage"
+		},
+		lifecycle: createGcsLifecycle(ctx),
+		async read(path) {
+			return await gcsRead(ctx, path);
+		},
+		async write(path, data) {
+			await gcsWrite(ctx, path, data);
+		},
+		async delete(path) {
+			await gcsDelete(ctx, path);
+		},
+		async exists(path) {
+			return await gcsExists(ctx, path);
+		},
+		async list(listPrefix) {
+			return await gcsList(ctx, listPrefix);
+		},
+		async writeStream(path, stream) {
+			await gcsWriteStream(ctx, path, stream);
+		},
+		async readStream(path) {
+			return await gcsReadStream(ctx, path);
+		}
+	};
+}
+//#endregion
+export { createGcsStorage, gcsKey };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Google Cloud Storage adapter for StoryShelf.\n *\n * Server-side blob storage for screenshots, diffs, and Storybook archives.\n * The factory wires per-concern modules (client, lifecycle, operations,\n * streams); key and option helpers are re-exported below.\n */\nimport type { StorageAdapter } from \"@storyshelf/core/adapter/storage\";\nimport { createGcsContext } from \"./client.ts\";\nimport { createGcsLifecycle } from \"./lifecycle.ts\";\nimport { gcsDelete, gcsExists, gcsList, gcsRead, gcsWrite } from \"./operations.ts\";\nimport { gcsReadStream, gcsWriteStream } from \"./streams.ts\";\nimport type { GcsStorageOptions } from \"./types.ts\";\n\ndeclare const __PKG_VERSION__: string | undefined;\n\n/**\n * Create a Google Cloud Storage (GCS) StorageAdapter.\n *\n * @param options - GCS configuration options.\n * @returns A StorageAdapter backed by the configured GCS bucket.\n */\nexport function createGcsStorage(options: GcsStorageOptions): StorageAdapter {\n  const ctx = createGcsContext(options);\n\n  return {\n    metadata: {\n      name: \"GCS Storage\",\n      version: (globalThis as unknown as { __PKG_VERSION__?: string }).__PKG_VERSION__ ?? \"0.0.0\",\n      description: \"Google Cloud Storage adapter\",\n      kind: \"gcs\",\n      category: \"storage\",\n    },\n    lifecycle: createGcsLifecycle(ctx),\n    async read(path) {\n      return await gcsRead(ctx, path);\n    },\n    async write(path, data) {\n      await gcsWrite(ctx, path, data);\n    },\n    async delete(path) {\n      await gcsDelete(ctx, path);\n    },\n    async exists(path) {\n      return await gcsExists(ctx, path);\n    },\n    async list(listPrefix) {\n      return await gcsList(ctx, listPrefix);\n    },\n    async writeStream(path, stream) {\n      await gcsWriteStream(ctx, path, stream);\n    },\n    async readStream(path) {\n      return await gcsReadStream(ctx, path);\n    },\n  };\n}\n\nexport type { GcsStorageOptions } from \"./types.ts\";\nexport { gcsKey } from \"./keys.ts\";\n"],"mappings":";;;;;;;;;;;;;;;AAsBA,SAAgB,iBAAiB,SAA4C;CAC3E,MAAM,MAAM,iBAAiB,OAAO;CAEpC,OAAO;EACL,UAAU;GACR,MAAM;GACN,SAAU,WAAuD,mBAAmB;GACpF,aAAa;GACb,MAAM;GACN,UAAU;EACZ;EACA,WAAW,mBAAmB,GAAG;EACjC,MAAM,KAAK,MAAM;GACf,OAAO,MAAM,QAAQ,KAAK,IAAI;EAChC;EACA,MAAM,MAAM,MAAM,MAAM;GACtB,MAAM,SAAS,KAAK,MAAM,IAAI;EAChC;EACA,MAAM,OAAO,MAAM;GACjB,MAAM,UAAU,KAAK,IAAI;EAC3B;EACA,MAAM,OAAO,MAAM;GACjB,OAAO,MAAM,UAAU,KAAK,IAAI;EAClC;EACA,MAAM,KAAK,YAAY;GACrB,OAAO,MAAM,QAAQ,KAAK,UAAU;EACtC;EACA,MAAM,YAAY,MAAM,QAAQ;GAC9B,MAAM,eAAe,KAAK,MAAM,MAAM;EACxC;EACA,MAAM,WAAW,MAAM;GACrB,OAAO,MAAM,cAAc,KAAK,IAAI;EACtC;CACF;AACF"}

package/dist/keys.d.mts

@@ -0,0 +1,9 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/keys.d.ts
+/** Key join/split for GCS object keys. */
+/** Join an optional key prefix with a storage path. */
+declare function gcsKey(prefix: string, path: string): string;
+//#endregion
+export { gcsKey };
+//# sourceMappingURL=keys.d.mts.map

package/dist/keys.mjs

@@ -0,0 +1,17 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/keys.ts
+/** Key join/split for GCS object keys. */
+/** Join an optional key prefix with a storage path. */
+function gcsKey(prefix, path) {
+	return prefix === "" ? path : `${prefix}/${path}`;
+}
+/** Strip a key prefix from a full GCS object name (inverse of gcsKey). */
+function gcsRel(prefix, key) {
+	return prefix === "" ? key : key.slice(prefix.length + 1);
+}
+//#endregion
+export { gcsKey, gcsRel };
+
+//# sourceMappingURL=keys.mjs.map

package/dist/keys.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.mjs","names":[],"sources":["../src/keys.ts"],"sourcesContent":["/** Key join/split for GCS object keys. */\n\n/** Join an optional key prefix with a storage path. */\nexport function gcsKey(prefix: string, path: string): string {\n  return prefix === \"\" ? path : `${prefix}/${path}`;\n}\n\n/** Strip a key prefix from a full GCS object name (inverse of gcsKey). */\nexport function gcsRel(prefix: string, key: string): string {\n  return prefix === \"\" ? key : key.slice(prefix.length + 1);\n}\n"],"mappings":";;;;;;AAGA,SAAgB,OAAO,QAAgB,MAAsB;CAC3D,OAAO,WAAW,KAAK,OAAO,GAAG,OAAO,GAAG;AAC7C;;AAGA,SAAgB,OAAO,QAAgB,KAAqB;CAC1D,OAAO,WAAW,KAAK,MAAM,IAAI,MAAM,OAAO,SAAS,CAAC;AAC1D"}

package/dist/lifecycle.mjs

@@ -0,0 +1,30 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/lifecycle.ts
+/** Build the setup/health/teardown hooks probing a GCS bucket. */
+function createGcsLifecycle(ctx) {
+	return {
+		setup: async () => {
+			await ctx.bucket.getFiles(gcsHealthQuery(ctx.prefix));
+		},
+		teardown: async () => {
+			await Promise.resolve();
+		},
+		health: async () => {
+			await ctx.bucket.getFiles(gcsHealthQuery(ctx.prefix));
+			return { ok: true };
+		}
+	};
+}
+/** Single-object probe query scoped to the configured prefix. */
+function gcsHealthQuery(prefix) {
+	return prefix === "" ? { maxResults: 1 } : {
+		prefix: `${prefix}/`,
+		maxResults: 1
+	};
+}
+//#endregion
+export { createGcsLifecycle, gcsHealthQuery };
+
+//# sourceMappingURL=lifecycle.mjs.map

package/dist/lifecycle.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.mjs","names":[],"sources":["../src/lifecycle.ts"],"sourcesContent":["/** Setup/health/teardown lifecycle for the GCS adapter. */\nimport type { StorageAdapter } from \"@storyshelf/core/adapter/storage\";\nimport type { GcsContext } from \"./client.ts\";\n\n/** Build the setup/health/teardown hooks probing a GCS bucket. */\nexport function createGcsLifecycle(ctx: GcsContext): NonNullable<StorageAdapter[\"lifecycle\"]> {\n  return {\n    setup: async () => {\n      await ctx.bucket.getFiles(gcsHealthQuery(ctx.prefix));\n    },\n    teardown: async () => {\n      // GCS Storage exposes no close — connections are process-global.\n      await Promise.resolve();\n    },\n    health: async () => {\n      await ctx.bucket.getFiles(gcsHealthQuery(ctx.prefix));\n      return { ok: true };\n    },\n  };\n}\n\n/** Single-object probe query scoped to the configured prefix. */\nexport function gcsHealthQuery(prefix: string): { prefix?: string; maxResults: number } {\n  return prefix === \"\" ? { maxResults: 1 } : { prefix: `${prefix}/`, maxResults: 1 };\n}\n"],"mappings":";;;;;AAKA,SAAgB,mBAAmB,KAA2D;CAC5F,OAAO;EACL,OAAO,YAAY;GACjB,MAAM,IAAI,OAAO,SAAS,eAAe,IAAI,MAAM,CAAC;EACtD;EACA,UAAU,YAAY;GAEpB,MAAM,QAAQ,QAAQ;EACxB;EACA,QAAQ,YAAY;GAClB,MAAM,IAAI,OAAO,SAAS,eAAe,IAAI,MAAM,CAAC;GACpD,OAAO,EAAE,IAAI,KAAK;EACpB;CACF;AACF;;AAGA,SAAgB,eAAe,QAAyD;CACtF,OAAO,WAAW,KAAK,EAAE,YAAY,EAAE,IAAI;EAAE,QAAQ,GAAG,OAAO;EAAI,YAAY;CAAE;AACnF"}

package/dist/operations.mjs

@@ -0,0 +1,51 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { isNotFound } from "./errors.mjs";
+import { gcsKey, gcsRel } from "./keys.mjs";
+//#region src/operations.ts
+/** Download the full bytes stored at `path`. */
+async function gcsRead(ctx, path) {
+	const [data] = await ctx.bucket.file(gcsKey(ctx.prefix, path)).download();
+	return data;
+}
+/** Save `data` at `path`, overwriting any existing object. */
+async function gcsWrite(ctx, path, data) {
+	await ctx.bucket.file(gcsKey(ctx.prefix, path)).save(data);
+}
+/** Delete the object at `path`, ignoring not-found errors. */
+async function gcsDelete(ctx, path) {
+	try {
+		await ctx.bucket.file(gcsKey(ctx.prefix, path)).delete();
+	} catch (error) {
+		if (!isNotFound(error)) throw error;
+	}
+}
+/** Return whether an object exists at `path`. */
+async function gcsExists(ctx, path) {
+	const [exists] = await ctx.bucket.file(gcsKey(ctx.prefix, path)).exists();
+	return exists;
+}
+/** List paths under `listPrefix`, following pagination to exhaustion. */
+async function gcsList(ctx, listPrefix) {
+	const prefix = gcsKey(ctx.prefix, listPrefix);
+	const results = [];
+	let query = prefix === "" ? { autoPaginate: false } : {
+		prefix,
+		autoPaginate: false
+	};
+	while (query !== void 0) {
+		const [files, nextQuery] = await ctx.bucket.getFiles(query);
+		for (const file of files) results.push(gcsRel(ctx.prefix, file.name));
+		query = nextQueryQuery(nextQuery);
+	}
+	return results;
+}
+function nextQueryQuery(nextQuery) {
+	if (!nextQuery || typeof nextQuery !== "object") return;
+	return nextQuery.pageToken ? nextQuery : void 0;
+}
+//#endregion
+export { gcsDelete, gcsExists, gcsList, gcsRead, gcsWrite };
+
+//# sourceMappingURL=operations.mjs.map

package/dist/operations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.mjs","names":[],"sources":["../src/operations.ts"],"sourcesContent":["/** Buffered CRUD (read/write/delete/exists) plus paginated listing for GCS. */\nimport type { GcsContext } from \"./client.ts\";\nimport { isNotFound } from \"./errors.ts\";\nimport { gcsKey, gcsRel } from \"./keys.ts\";\n\n/** Download the full bytes stored at `path`. */\nexport async function gcsRead(ctx: GcsContext, path: string): Promise<Buffer> {\n  const file = ctx.bucket.file(gcsKey(ctx.prefix, path));\n  const [data] = await file.download();\n  return data;\n}\n\n/** Save `data` at `path`, overwriting any existing object. */\nexport async function gcsWrite(ctx: GcsContext, path: string, data: Buffer): Promise<void> {\n  await ctx.bucket.file(gcsKey(ctx.prefix, path)).save(data);\n}\n\n/** Delete the object at `path`, ignoring not-found errors. */\nexport async function gcsDelete(ctx: GcsContext, path: string): Promise<void> {\n  try {\n    await ctx.bucket.file(gcsKey(ctx.prefix, path)).delete();\n  } catch (error) {\n    if (!isNotFound(error)) {\n      throw error;\n    }\n  }\n}\n\n/** Return whether an object exists at `path`. */\nexport async function gcsExists(ctx: GcsContext, path: string): Promise<boolean> {\n  const [exists] = await ctx.bucket.file(gcsKey(ctx.prefix, path)).exists();\n  return exists;\n}\n\n/** List paths under `listPrefix`, following pagination to exhaustion. */\nexport async function gcsList(ctx: GcsContext, listPrefix: string): Promise<string[]> {\n  const prefix = gcsKey(ctx.prefix, listPrefix);\n  const results: string[] = [];\n  let query: Record<string, unknown> | undefined =\n    prefix === \"\" ? { autoPaginate: false } : { prefix, autoPaginate: false };\n  while (query !== undefined) {\n    // oxlint-disable-next-line eslint/no-await-in-loop -- pagination requires sequential awaits\n    const [files, nextQuery] = (await ctx.bucket.getFiles(query as never)) as unknown as [\n      { name: string }[],\n      Record<string, unknown> | null,\n    ];\n    for (const file of files) {\n      results.push(gcsRel(ctx.prefix, file.name));\n    }\n    query = nextQueryQuery(nextQuery);\n  }\n  return results;\n}\n\nfunction nextQueryQuery(\n  nextQuery: Record<string, unknown> | null,\n): Record<string, unknown> | undefined {\n  if (!nextQuery || typeof nextQuery !== \"object\") {\n    return undefined;\n  }\n  const token = (nextQuery as { pageToken?: string }).pageToken;\n  return token ? nextQuery : undefined;\n}\n"],"mappings":";;;;;;;AAMA,eAAsB,QAAQ,KAAiB,MAA+B;CAE5E,MAAM,CAAC,QAAQ,MADF,IAAI,OAAO,KAAK,OAAO,IAAI,QAAQ,IAAI,CAC5B,CAAC,CAAC,SAAS;CACnC,OAAO;AACT;;AAGA,eAAsB,SAAS,KAAiB,MAAc,MAA6B;CACzF,MAAM,IAAI,OAAO,KAAK,OAAO,IAAI,QAAQ,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI;AAC3D;;AAGA,eAAsB,UAAU,KAAiB,MAA6B;CAC5E,IAAI;EACF,MAAM,IAAI,OAAO,KAAK,OAAO,IAAI,QAAQ,IAAI,CAAC,CAAC,CAAC,OAAO;CACzD,SAAS,OAAO;EACd,IAAI,CAAC,WAAW,KAAK,GACnB,MAAM;CAEV;AACF;;AAGA,eAAsB,UAAU,KAAiB,MAAgC;CAC/E,MAAM,CAAC,UAAU,MAAM,IAAI,OAAO,KAAK,OAAO,IAAI,QAAQ,IAAI,CAAC,CAAC,CAAC,OAAO;CACxE,OAAO;AACT;;AAGA,eAAsB,QAAQ,KAAiB,YAAuC;CACpF,MAAM,SAAS,OAAO,IAAI,QAAQ,UAAU;CAC5C,MAAM,UAAoB,CAAC;CAC3B,IAAI,QACF,WAAW,KAAK,EAAE,cAAc,MAAM,IAAI;EAAE;EAAQ,cAAc;CAAM;CAC1E,OAAO,UAAU,KAAA,GAAW;EAE1B,MAAM,CAAC,OAAO,aAAc,MAAM,IAAI,OAAO,SAAS,KAAc;EAIpE,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,IAAI,CAAC;EAE5C,QAAQ,eAAe,SAAS;CAClC;CACA,OAAO;AACT;AAEA,SAAS,eACP,WACqC;CACrC,IAAI,CAAC,aAAa,OAAO,cAAc,UACrC;CAGF,OADe,UAAqC,YACrC,YAAY,KAAA;AAC7B"}

package/dist/streams.mjs

@@ -0,0 +1,30 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { gcsKey } from "./keys.mjs";
+import { pipeline } from "node:stream/promises";
+//#region src/streams.ts
+/** Stream `stream` to `path`, deleting the partial object when the pipeline fails. */
+async function gcsWriteStream(ctx, path, stream) {
+	const file = ctx.bucket.file(gcsKey(ctx.prefix, path));
+	const dest = file.createWriteStream({ resumable: false });
+	try {
+		await pipeline(stream, dest);
+	} catch (error) {
+		try {
+			await file.delete({ ignoreNotFound: true });
+		} catch {}
+		throw error;
+	}
+}
+/** Open a readable for the bytes at `path`; rejects when the object is missing. */
+async function gcsReadStream(ctx, path) {
+	const file = ctx.bucket.file(gcsKey(ctx.prefix, path));
+	const [exists] = await file.exists();
+	if (!exists) throw new Error(`No object at "${path}"`);
+	return file.createReadStream();
+}
+//#endregion
+export { gcsReadStream, gcsWriteStream };
+
+//# sourceMappingURL=streams.mjs.map

package/dist/streams.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.mjs","names":[],"sources":["../src/streams.ts"],"sourcesContent":["/** Streaming reads/writes for GCS objects, with failure cleanup. */\nimport type { Readable } from \"node:stream\";\nimport { pipeline } from \"node:stream/promises\";\nimport type { GcsContext } from \"./client.ts\";\nimport { gcsKey } from \"./keys.ts\";\n\n/** Stream `stream` to `path`, deleting the partial object when the pipeline fails. */\nexport async function gcsWriteStream(\n  ctx: GcsContext,\n  path: string,\n  stream: Readable,\n): Promise<void> {\n  const file = ctx.bucket.file(gcsKey(ctx.prefix, path));\n  const dest = file.createWriteStream({ resumable: false });\n  try {\n    await pipeline(stream, dest);\n  } catch (error) {\n    try {\n      await file.delete({ ignoreNotFound: true });\n    } catch {\n      // ignore cleanup failure, rethrow original error\n    }\n    throw error;\n  }\n}\n\n/** Open a readable for the bytes at `path`; rejects when the object is missing. */\nexport async function gcsReadStream(ctx: GcsContext, path: string): Promise<Readable> {\n  const file = ctx.bucket.file(gcsKey(ctx.prefix, path));\n  const [exists] = await file.exists();\n  if (!exists) {\n    throw new Error(`No object at \"${path}\"`);\n  }\n  return file.createReadStream();\n}\n"],"mappings":";;;;;;;AAOA,eAAsB,eACpB,KACA,MACA,QACe;CACf,MAAM,OAAO,IAAI,OAAO,KAAK,OAAO,IAAI,QAAQ,IAAI,CAAC;CACrD,MAAM,OAAO,KAAK,kBAAkB,EAAE,WAAW,MAAM,CAAC;CACxD,IAAI;EACF,MAAM,SAAS,QAAQ,IAAI;CAC7B,SAAS,OAAO;EACd,IAAI;GACF,MAAM,KAAK,OAAO,EAAE,gBAAgB,KAAK,CAAC;EAC5C,QAAQ,CAER;EACA,MAAM;CACR;AACF;;AAGA,eAAsB,cAAc,KAAiB,MAAiC;CACpF,MAAM,OAAO,IAAI,OAAO,KAAK,OAAO,IAAI,QAAQ,IAAI,CAAC;CACrD,MAAM,CAAC,UAAU,MAAM,KAAK,OAAO;CACnC,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,iBAAiB,KAAK,EAAE;CAE1C,OAAO,KAAK,iBAAiB;AAC/B"}

package/dist/types.d.mts

@@ -0,0 +1,24 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Storage } from "@google-cloud/storage";
+//#region src/types.d.ts
+/** Options for configuring a GCS storage adapter. */
+interface GcsStorageOptions {
+  /** GCS bucket name. */
+  bucket: string;
+  /** Optional key prefix applied to all stored objects. */
+  prefix?: string;
+  /** Pre-configured GCS client. Defaults to a client built from the other options. */
+  client?: Storage;
+  /** GCP project ID (defaults to ADC). */
+  projectId?: string;
+  /** Path to service-account JSON key file. */
+  keyFilename?: string;
+  /** Service-account credentials object. */
+  credentials?: Record<string, unknown>;
+  /** Custom API endpoint (e.g. emulator: http://localhost:9090). */
+  apiEndpoint?: string;
+}
+//#endregion
+export { GcsStorageOptions };
+//# sourceMappingURL=types.d.mts.map

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@storyshelf/storage-gcs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.3",
+  "description": "Google Cloud Storage adapter for StoryShelf.",
+  "keywords": [
+    "gcs",
+    "google-cloud-storage",
+    "self-hosted",
+    "storage",
+    "storybook"
+  ],
+  "homepage": "https://github.com/GuptaSiddhant/StoryShelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/StoryShelf/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/StoryShelf.git",
+    "directory": "packages/storage-gcs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "vitest run",
+    "prepublishOnly": "nub run build"
+  },
+  "dependencies": {
+    "@google-cloud/storage": "^7.13.0",
+    "@storyshelf/core": "0.5.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "jsr": {
+    "runtimeCompat": {
+      "node": true,
+      "deno": true,
+      "browser": false,
+      "workerd": false,
+      "bun": true
+    }
+  }
+}