@storyshelf/storage-azure 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

@@ -0,0 +1,90 @@
+# @storyshelf/storage-azure
+
+Azure Blob Storage adapter for StoryShelf: reads and writes blobs to an Azure Storage container, including Azurite emulator support.
+
+## Install
+
+```sh
+nub add @storyshelf/storage-azure
+```
+
+or
+
+```sh
+npm install @storyshelf/storage-azure
+```
+
+## Quick start
+
+```ts
+import { createAzureStorage } from "@storyshelf/storage-azure";
+import { createShelfApp } from "@storyshelf/app";
+
+// Via connection string (recommended for local / Azurite)
+const storage = createAzureStorage({
+  container: "storyshelf",
+  prefix: "storyshelf", // optional
+  connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
+});
+
+// Via account name + key
+const storage2 = createAzureStorage({
+  container: "storyshelf",
+  accountName: "myaccount",
+  accountKey: process.env.AZURE_STORAGE_KEY,
+  accountUrl: "https://myaccount.blob.core.windows.net", // optional, derived from accountName if omitted
+});
+
+const app = createShelfApp({ database, storage });
+```
+
+Inject a pre-configured client (tests / custom credential rotation):
+
+```ts
+import { BlobServiceClient } from "@azure/storage-blob";
+
+const service = BlobServiceClient.fromConnectionString(connStr);
+const containerClient = service.getContainerClient("storyshelf");
+const storage = createAzureStorage({ container: "storyshelf", client: containerClient });
+```
+
+Azurite (local emulator):
+
+```ts
+const storage = createAzureStorage({
+  container: "storyshelf",
+  connectionString:
+    "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;",
+});
+```
+
+## API
+
+### `AzureStorageOptions`
+
+```ts
+interface AzureStorageOptions {
+  container: string; // required container name
+  prefix?: string; // optional blob prefix, defaults to ""
+  client?: ContainerClient; // optional pre-configured container client
+  connectionString?: string; // optional Azure connection string
+  accountName?: string; // optional storage account name
+  accountKey?: string; // optional storage account key
+  accountUrl?: string; // optional blob service URL (e.g. https://myaccount.blob.core.windows.net)
+  sasToken?: string; // optional SAS token (without leading ? OK)
+}
+```
+
+### `createAzureStorage(options: AzureStorageOptions): StorageAdapter`
+
+Creates a `StorageAdapter` backed by the configured Azure container. The returned adapter implements every method of the `StorageAdapter` interface (`read`, `write`, `delete`, `exists`, `list(prefix)`, `readStream`, `writeStream`).
+
+### `azureKey(prefix: string, path: string): string`
+
+Helper that joins a storage prefix with a relative path into a blob name.
+
+## How it fits in
+
+`storage-azure` is the `storage` option for `createShelfApp` in Azure deployments. It implements the same `StorageAdapter` interface as `@storyshelf/storage-local`, `@storyshelf/storage-s3`, and `@storyshelf/storage-gcs`, so switching between local disk, S3, GCS, and Azure requires no changes elsewhere.
+
+See `docs/architecture.md` and ADR 0006.

package/dist/client.mjs

@@ -0,0 +1,32 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";
+//#region src/client.ts
+/** Resolve the container client for the configured credentials. */
+function resolveContainerClient(options, containerName) {
+	if (options.client) return options.client;
+	if (options.connectionString) return BlobServiceClient.fromConnectionString(options.connectionString).getContainerClient(containerName);
+	return resolveFromAccount(options, containerName);
+}
+function resolveFromAccount(options, containerName) {
+	const url = options.accountUrl ?? buildAccountUrl(options.accountName);
+	if (!url) throw new Error("createAzureStorage: provide `client`, `connectionString`, or `accountName`/`accountUrl`");
+	if (options.accountName && options.accountKey) {
+		const cred = new StorageSharedKeyCredential(options.accountName, options.accountKey);
+		return new BlobServiceClient(url, cred).getContainerClient(containerName);
+	}
+	if (options.sasToken) {
+		const token = options.sasToken.replace(/^\?/u, "");
+		return new BlobServiceClient(`${url}?${token}`).getContainerClient(containerName);
+	}
+	return new BlobServiceClient(url).getContainerClient(containerName);
+}
+function buildAccountUrl(accountName) {
+	if (!accountName) return;
+	return `https://${accountName}.blob.core.windows.net`;
+}
+//#endregion
+export { resolveContainerClient };
+
+//# sourceMappingURL=client.mjs.map

package/dist/client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.mjs","names":[],"sources":["../src/client.ts"],"sourcesContent":["import {\n  BlobServiceClient,\n  StorageSharedKeyCredential,\n  type ContainerClient,\n} from \"@azure/storage-blob\";\nimport type { AzureStorageOptions } from \"./types.ts\";\n\n/** Resolve the container client for the configured credentials. */\nexport function resolveContainerClient(\n  options: AzureStorageOptions,\n  containerName: string,\n): ContainerClient {\n  if (options.client) {\n    return options.client;\n  }\n  if (options.connectionString) {\n    return BlobServiceClient.fromConnectionString(options.connectionString).getContainerClient(\n      containerName,\n    );\n  }\n  return resolveFromAccount(options, containerName);\n}\n\n/** Shared Azure container context threaded through operations. */\nexport interface AzureContext {\n  container: ContainerClient;\n  prefix: string;\n}\n\nfunction resolveFromAccount(options: AzureStorageOptions, containerName: string): ContainerClient {\n  const url = options.accountUrl ?? buildAccountUrl(options.accountName);\n  if (!url) {\n    throw new Error(\n      \"createAzureStorage: provide `client`, `connectionString`, or `accountName`/`accountUrl`\",\n    );\n  }\n  if (options.accountName && options.accountKey) {\n    const cred = new StorageSharedKeyCredential(options.accountName, options.accountKey);\n    return new BlobServiceClient(url, cred).getContainerClient(containerName);\n  }\n  if (options.sasToken) {\n    const token = options.sasToken.replace(/^\\?/u, \"\");\n    return new BlobServiceClient(`${url}?${token}`).getContainerClient(containerName);\n  }\n  return new BlobServiceClient(url).getContainerClient(containerName);\n}\n\nfunction buildAccountUrl(accountName: string | undefined): string | undefined {\n  if (!accountName) {\n    return undefined;\n  }\n  return `https://${accountName}.blob.core.windows.net`;\n}\n"],"mappings":";;;;;;AAQA,SAAgB,uBACd,SACA,eACiB;CACjB,IAAI,QAAQ,QACV,OAAO,QAAQ;CAEjB,IAAI,QAAQ,kBACV,OAAO,kBAAkB,qBAAqB,QAAQ,gBAAgB,CAAC,CAAC,mBACtE,aACF;CAEF,OAAO,mBAAmB,SAAS,aAAa;AAClD;AAQA,SAAS,mBAAmB,SAA8B,eAAwC;CAChG,MAAM,MAAM,QAAQ,cAAc,gBAAgB,QAAQ,WAAW;CACrE,IAAI,CAAC,KACH,MAAM,IAAI,MACR,yFACF;CAEF,IAAI,QAAQ,eAAe,QAAQ,YAAY;EAC7C,MAAM,OAAO,IAAI,2BAA2B,QAAQ,aAAa,QAAQ,UAAU;EACnF,OAAO,IAAI,kBAAkB,KAAK,IAAI,CAAC,CAAC,mBAAmB,aAAa;CAC1E;CACA,IAAI,QAAQ,UAAU;EACpB,MAAM,QAAQ,QAAQ,SAAS,QAAQ,QAAQ,EAAE;EACjD,OAAO,IAAI,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,mBAAmB,aAAa;CAClF;CACA,OAAO,IAAI,kBAAkB,GAAG,CAAC,CAAC,mBAAmB,aAAa;AACpE;AAEA,SAAS,gBAAgB,aAAqD;CAC5E,IAAI,CAAC,aACH;CAEF,OAAO,WAAW,YAAY;AAChC"}

package/dist/errors.mjs

@@ -0,0 +1,41 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import "node:stream";
+//#region src/errors.ts
+/** Not-found guards and stream/collect helpers for Azure blob I/O. */
+/** True when an Azure SDK error means the blob (or container) is missing. */
+function isNotFound(error) {
+	const err = error;
+	if (err.statusCode === 404) return true;
+	return err.code === "BlobNotFound" || err.code === "ContainerNotFound" || err.code === "404";
+}
+/** Download a blob through the `download()` response stream. */
+async function collectDownload(blob) {
+	const body = (await blob.download()).readableStreamBody;
+	if (!body) return Buffer.alloc(0);
+	const chunks = [];
+	for await (const chunk of body) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk));
+	return Buffer.concat(chunks);
+}
+/** Buffer an incoming readable into a single Buffer. */
+async function collectStream(stream) {
+	const chunks = [];
+	for await (const chunk of stream) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk));
+	return Buffer.concat(chunks);
+}
+/** Best-effort blob delete used to clean up after failed stream uploads. */
+async function deleteBlobQuiet(blob) {
+	try {
+		const withDelete = blob;
+		if (typeof withDelete.deleteIfExists === "function") {
+			await withDelete.deleteIfExists();
+			return;
+		}
+		await withDelete.delete?.();
+	} catch {}
+}
+//#endregion
+export { collectDownload, collectStream, deleteBlobQuiet, isNotFound };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import type { ContainerClient } from \"@azure/storage-blob\";\nimport { Readable } from \"node:stream\";\n\n/** Not-found guards and stream/collect helpers for Azure blob I/O. */\n\n/** True when an Azure SDK error means the blob (or container) is missing. */\nexport function isNotFound(error: unknown): boolean {\n  const err = error as { statusCode?: number; code?: string };\n  if (err.statusCode === 404) {\n    return true;\n  }\n  return err.code === \"BlobNotFound\" || err.code === \"ContainerNotFound\" || err.code === \"404\";\n}\n\n/** Download a blob through the `download()` response stream. */\nexport async function collectDownload(\n  blob: ReturnType<ContainerClient[\"getBlockBlobClient\"]>,\n): Promise<Buffer> {\n  const response = await blob.download();\n  const body = response.readableStreamBody as unknown as Readable | undefined;\n  if (!body) {\n    return Buffer.alloc(0);\n  }\n  const chunks: Buffer[] = [];\n  for await (const chunk of body) {\n    chunks.push(typeof chunk === \"string\" ? Buffer.from(chunk) : Buffer.from(chunk as Uint8Array));\n  }\n  return Buffer.concat(chunks);\n}\n\n/** Buffer an incoming readable into a single Buffer. */\nexport async function collectStream(stream: Readable): Promise<Buffer> {\n  const chunks: Buffer[] = [];\n  for await (const chunk of stream) {\n    chunks.push(typeof chunk === \"string\" ? Buffer.from(chunk) : Buffer.from(chunk as Uint8Array));\n  }\n  return Buffer.concat(chunks);\n}\n\n/** Best-effort blob delete used to clean up after failed stream uploads. */\nexport async function deleteBlobQuiet(\n  blob: ReturnType<ContainerClient[\"getBlockBlobClient\"]>,\n): Promise<void> {\n  try {\n    const withDelete = blob as unknown as {\n      deleteIfExists?: () => Promise<void>;\n      delete?: () => Promise<void>;\n    };\n    if (typeof withDelete.deleteIfExists === \"function\") {\n      await withDelete.deleteIfExists();\n      return;\n    }\n    await withDelete.delete?.();\n  } catch {\n    // ignore - best-effort cleanup\n  }\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,WAAW,OAAyB;CAClD,MAAM,MAAM;CACZ,IAAI,IAAI,eAAe,KACrB,OAAO;CAET,OAAO,IAAI,SAAS,kBAAkB,IAAI,SAAS,uBAAuB,IAAI,SAAS;AACzF;;AAGA,eAAsB,gBACpB,MACiB;CAEjB,MAAM,QAAO,MADU,KAAK,SAAS,EAAA,CACf;CACtB,IAAI,CAAC,MACH,OAAO,OAAO,MAAM,CAAC;CAEvB,MAAM,SAAmB,CAAC;CAC1B,WAAW,MAAM,SAAS,MACxB,OAAO,KAAK,OAAO,UAAU,WAAW,OAAO,KAAK,KAAK,IAAI,OAAO,KAAK,KAAmB,CAAC;CAE/F,OAAO,OAAO,OAAO,MAAM;AAC7B;;AAGA,eAAsB,cAAc,QAAmC;CACrE,MAAM,SAAmB,CAAC;CAC1B,WAAW,MAAM,SAAS,QACxB,OAAO,KAAK,OAAO,UAAU,WAAW,OAAO,KAAK,KAAK,IAAI,OAAO,KAAK,KAAmB,CAAC;CAE/F,OAAO,OAAO,OAAO,MAAM;AAC7B;;AAGA,eAAsB,gBACpB,MACe;CACf,IAAI;EACF,MAAM,aAAa;EAInB,IAAI,OAAO,WAAW,mBAAmB,YAAY;GACnD,MAAM,WAAW,eAAe;GAChC;EACF;EACA,MAAM,WAAW,SAAS;CAC5B,QAAQ,CAER;AACF"}

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AzureStorageOptions } from "./types.mjs";
+import { azureKey } from "./keys.mjs";
+import { StorageAdapter } from "@storyshelf/core/adapter/storage";
+//#region src/index.d.ts
+/**
+ * Create an Azure Blob Storage-backed StorageAdapter.
+ *
+ * @param options - Azure configuration options.
+ * @returns A StorageAdapter backed by the configured Azure container.
+ */
+declare function createAzureStorage(options: AzureStorageOptions): StorageAdapter;
+//#endregion
+export { type AzureStorageOptions, azureKey, createAzureStorage };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,58 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { resolveContainerClient } from "./client.mjs";
+import { buildAzureLifecycle } from "./lifecycle.mjs";
+import { azureKey } from "./keys.mjs";
+import { azureDelete, azureExists, azureList, azureRead, azureWrite } from "./operations.mjs";
+import { azureReadStream, azureWriteStream } from "./streams.mjs";
+//#region src/index.ts
+/**
+* Create an Azure Blob Storage-backed StorageAdapter.
+*
+* @param options - Azure configuration options.
+* @returns A StorageAdapter backed by the configured Azure container.
+*/
+function createAzureStorage(options) {
+	const { container: containerName, prefix = "" } = options;
+	const container = resolveContainerClient(options, containerName);
+	const ctx = {
+		container,
+		prefix
+	};
+	return {
+		metadata: {
+			name: "Azure Blob Storage",
+			version: globalThis.__PKG_VERSION__ ?? "0.0.0",
+			description: "Azure Blob Storage adapter",
+			kind: "azure",
+			category: "storage"
+		},
+		lifecycle: buildAzureLifecycle(container, containerName),
+		async read(path) {
+			return await azureRead(ctx, path);
+		},
+		async write(path, data) {
+			await azureWrite(ctx, path, data);
+		},
+		async delete(path) {
+			await azureDelete(ctx, path);
+		},
+		async exists(path) {
+			return await azureExists(ctx, path);
+		},
+		async list(listPrefix) {
+			return await azureList(ctx, listPrefix);
+		},
+		async writeStream(path, stream) {
+			await azureWriteStream(ctx, path, stream);
+		},
+		async readStream(path) {
+			return await azureReadStream(ctx, path);
+		}
+	};
+}
+//#endregion
+export { azureKey, createAzureStorage };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Azure Blob Storage adapter for StoryShelf.\n *\n * Persists captured screenshots and diff overlays in an Azure Blob container.\n * The CLI uploads the built Storybook; the server renders stories with\n * Playwright and stores the resulting blobs here.\n */\nimport type { StorageAdapter } from \"@storyshelf/core/adapter/storage\";\nimport { resolveContainerClient, type AzureContext } from \"./client.ts\";\nimport { buildAzureLifecycle } from \"./lifecycle.ts\";\nimport { azureDelete, azureExists, azureList, azureRead, azureWrite } from \"./operations.ts\";\nimport { azureReadStream, azureWriteStream } from \"./streams.ts\";\nimport type { AzureStorageOptions } from \"./types.ts\";\n\ndeclare const __PKG_VERSION__: string | undefined;\n\n/**\n * Create an Azure Blob Storage-backed StorageAdapter.\n *\n * @param options - Azure configuration options.\n * @returns A StorageAdapter backed by the configured Azure container.\n */\nexport function createAzureStorage(options: AzureStorageOptions): StorageAdapter {\n  const { container: containerName, prefix = \"\" } = options;\n  const container = resolveContainerClient(options, containerName);\n  const ctx: AzureContext = { container, prefix };\n\n  return {\n    metadata: {\n      name: \"Azure Blob Storage\",\n      version: (globalThis as unknown as { __PKG_VERSION__?: string }).__PKG_VERSION__ ?? \"0.0.0\",\n      description: \"Azure Blob Storage adapter\",\n      kind: \"azure\",\n      category: \"storage\",\n    },\n    lifecycle: buildAzureLifecycle(container, containerName),\n    async read(path) {\n      return await azureRead(ctx, path);\n    },\n    async write(path, data) {\n      await azureWrite(ctx, path, data);\n    },\n    async delete(path) {\n      await azureDelete(ctx, path);\n    },\n    async exists(path) {\n      return await azureExists(ctx, path);\n    },\n    async list(listPrefix) {\n      return await azureList(ctx, listPrefix);\n    },\n    async writeStream(path, stream) {\n      await azureWriteStream(ctx, path, stream);\n    },\n    async readStream(path) {\n      return await azureReadStream(ctx, path);\n    },\n  };\n}\n\nexport type { AzureStorageOptions } from \"./types.ts\";\nexport { azureKey } from \"./keys.ts\";\n"],"mappings":";;;;;;;;;;;;;;;AAsBA,SAAgB,mBAAmB,SAA8C;CAC/E,MAAM,EAAE,WAAW,eAAe,SAAS,OAAO;CAClD,MAAM,YAAY,uBAAuB,SAAS,aAAa;CAC/D,MAAM,MAAoB;EAAE;EAAW;CAAO;CAE9C,OAAO;EACL,UAAU;GACR,MAAM;GACN,SAAU,WAAuD,mBAAmB;GACpF,aAAa;GACb,MAAM;GACN,UAAU;EACZ;EACA,WAAW,oBAAoB,WAAW,aAAa;EACvD,MAAM,KAAK,MAAM;GACf,OAAO,MAAM,UAAU,KAAK,IAAI;EAClC;EACA,MAAM,MAAM,MAAM,MAAM;GACtB,MAAM,WAAW,KAAK,MAAM,IAAI;EAClC;EACA,MAAM,OAAO,MAAM;GACjB,MAAM,YAAY,KAAK,IAAI;EAC7B;EACA,MAAM,OAAO,MAAM;GACjB,OAAO,MAAM,YAAY,KAAK,IAAI;EACpC;EACA,MAAM,KAAK,YAAY;GACrB,OAAO,MAAM,UAAU,KAAK,UAAU;EACxC;EACA,MAAM,YAAY,MAAM,QAAQ;GAC9B,MAAM,iBAAiB,KAAK,MAAM,MAAM;EAC1C;EACA,MAAM,WAAW,MAAM;GACrB,OAAO,MAAM,gBAAgB,KAAK,IAAI;EACxC;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 Azure blob names. */
+/** Join an optional prefix with a storage path. */
+declare function azureKey(prefix: string, path: string): string;
+//#endregion
+export { azureKey };
+//# 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 Azure blob names. */
+/** Join an optional prefix with a storage path. */
+function azureKey(prefix, path) {
+	return prefix === "" ? path : `${prefix}/${path}`;
+}
+/** Strip a storage prefix back off a blob name. */
+function azureRel(prefix, key) {
+	return prefix === "" ? key : key.slice(prefix.length + 1);
+}
+//#endregion
+export { azureKey, azureRel };
+
+//# 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 Azure blob names. */\n\n/** Join an optional prefix with a storage path. */\nexport function azureKey(prefix: string, path: string): string {\n  return prefix === \"\" ? path : `${prefix}/${path}`;\n}\n\n/** Strip a storage prefix back off a blob name. */\nexport function azureRel(prefix: string, key: string): string {\n  return prefix === \"\" ? key : key.slice(prefix.length + 1);\n}\n"],"mappings":";;;;;;AAGA,SAAgB,SAAS,QAAgB,MAAsB;CAC7D,OAAO,WAAW,KAAK,OAAO,GAAG,OAAO,GAAG;AAC7C;;AAGA,SAAgB,SAAS,QAAgB,KAAqB;CAC5D,OAAO,WAAW,KAAK,MAAM,IAAI,MAAM,OAAO,SAAS,CAAC;AAC1D"}

package/dist/lifecycle.mjs

@@ -0,0 +1,36 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/lifecycle.ts
+/** Build the setup/health/teardown lifecycle for an Azure container. */
+function buildAzureLifecycle(container, containerName) {
+	return {
+		setup: async () => {
+			await containerExists(container, containerName);
+		},
+		teardown: async () => {
+			await Promise.resolve();
+		},
+		health: async () => {
+			await containerExists(container, containerName);
+			return { ok: true };
+		}
+	};
+}
+async function containerExists(container, containerName) {
+	const exists = container.exists;
+	if (typeof exists === "function") {
+		if (!await exists.call(container)) throw new Error(`Container not found: ${containerName}`);
+		return;
+	}
+	const iterator = container.listBlobsFlat({ prefix: "" })[Symbol.asyncIterator]();
+	try {
+		await iterator.next();
+	} finally {
+		await iterator.return?.();
+	}
+}
+//#endregion
+export { buildAzureLifecycle };
+
+//# sourceMappingURL=lifecycle.mjs.map

package/dist/lifecycle.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.mjs","names":[],"sources":["../src/lifecycle.ts"],"sourcesContent":["import type { ContainerClient } from \"@azure/storage-blob\";\nimport type { StorageAdapter } from \"@storyshelf/core/adapter/storage\";\n\n/** Build the setup/health/teardown lifecycle for an Azure container. */\nexport function buildAzureLifecycle(\n  container: ContainerClient,\n  containerName: string,\n): StorageAdapter[\"lifecycle\"] {\n  return {\n    setup: async () => {\n      await containerExists(container, containerName);\n    },\n    teardown: async () => {\n      // ContainerClient holds no closable handle — sockets are process-global.\n      await Promise.resolve();\n    },\n    health: async () => {\n      await containerExists(container, containerName);\n      return { ok: true };\n    },\n  };\n}\n\nasync function containerExists(container: ContainerClient, containerName: string): Promise<void> {\n  const exists = (container as unknown as { exists?: () => Promise<boolean> }).exists;\n  if (typeof exists === \"function\") {\n    const ok = await exists.call(container);\n    if (!ok) {\n      throw new Error(`Container not found: ${containerName}`);\n    }\n    return;\n  }\n  const iterator = container.listBlobsFlat({ prefix: \"\" })[Symbol.asyncIterator]();\n  try {\n    await iterator.next();\n  } finally {\n    await (iterator as { return?: () => Promise<unknown> }).return?.();\n  }\n}\n"],"mappings":";;;;;AAIA,SAAgB,oBACd,WACA,eAC6B;CAC7B,OAAO;EACL,OAAO,YAAY;GACjB,MAAM,gBAAgB,WAAW,aAAa;EAChD;EACA,UAAU,YAAY;GAEpB,MAAM,QAAQ,QAAQ;EACxB;EACA,QAAQ,YAAY;GAClB,MAAM,gBAAgB,WAAW,aAAa;GAC9C,OAAO,EAAE,IAAI,KAAK;EACpB;CACF;AACF;AAEA,eAAe,gBAAgB,WAA4B,eAAsC;CAC/F,MAAM,SAAU,UAA6D;CAC7E,IAAI,OAAO,WAAW,YAAY;EAEhC,IAAI,CAAC,MADY,OAAO,KAAK,SAAS,GAEpC,MAAM,IAAI,MAAM,wBAAwB,eAAe;EAEzD;CACF;CACA,MAAM,WAAW,UAAU,cAAc,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC,OAAO,cAAc,CAAC;CAC/E,IAAI;EACF,MAAM,SAAS,KAAK;CACtB,UAAU;EACR,MAAO,SAAiD,SAAS;CACnE;AACF"}

package/dist/operations.mjs

@@ -0,0 +1,54 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { collectDownload, isNotFound } from "./errors.mjs";
+import { azureKey, azureRel } from "./keys.mjs";
+//#region src/operations.ts
+/** Buffered Azure blob CRUD with SDK-version duck-typing and async-iterator list. */
+/** Download a blob, preferring `downloadToBuffer` when the SDK offers it. */
+async function azureRead(ctx, path) {
+	const blob = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));
+	if (typeof blob.downloadToBuffer === "function") return await blob.downloadToBuffer();
+	return await collectDownload(blob);
+}
+/** Upload a buffer, accepting either `uploadData` or `upload` SDK shapes. */
+async function azureWrite(ctx, path, data) {
+	const withData = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));
+	if (typeof withData.uploadData === "function") {
+		await withData.uploadData(data);
+		return;
+	}
+	if (typeof withData.upload === "function") {
+		await withData.upload(data, data.length);
+		return;
+	}
+	throw new Error("Azure Blob client does not support upload");
+}
+/** Delete a blob, treating missing blobs as success. */
+async function azureDelete(ctx, path) {
+	const withDelete = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));
+	if (typeof withDelete.deleteIfExists === "function") {
+		await withDelete.deleteIfExists();
+		return;
+	}
+	try {
+		await withDelete.delete?.();
+	} catch (error) {
+		if (!isNotFound(error)) throw error;
+	}
+}
+/** Check whether a blob exists. */
+async function azureExists(ctx, path) {
+	return await ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path)).exists();
+}
+/** List blob names under a prefix, with the storage prefix stripped. */
+async function azureList(ctx, listPrefix) {
+	const prefix = azureKey(ctx.prefix, listPrefix);
+	const blobs = [];
+	for await (const item of ctx.container.listBlobsFlat(prefix === "" ? void 0 : { prefix })) blobs.push(azureRel(ctx.prefix, item.name));
+	return blobs;
+}
+//#endregion
+export { azureDelete, azureExists, azureList, azureRead, azureWrite };
+
+//# sourceMappingURL=operations.mjs.map

package/dist/operations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.mjs","names":[],"sources":["../src/operations.ts"],"sourcesContent":["import type { AzureContext } from \"./client.ts\";\nimport { collectDownload, isNotFound } from \"./errors.ts\";\nimport { azureKey, azureRel } from \"./keys.ts\";\n\n/** Buffered Azure blob CRUD with SDK-version duck-typing and async-iterator list. */\n\n/** Download a blob, preferring `downloadToBuffer` when the SDK offers it. */\nexport async function azureRead(ctx: AzureContext, path: string): Promise<Buffer> {\n  const blob = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));\n  if (\n    typeof (blob as unknown as { downloadToBuffer?: () => Promise<Buffer> }).downloadToBuffer ===\n    \"function\"\n  ) {\n    return await (\n      blob as unknown as { downloadToBuffer: () => Promise<Buffer> }\n    ).downloadToBuffer();\n  }\n  return await collectDownload(blob);\n}\n\n/** Upload a buffer, accepting either `uploadData` or `upload` SDK shapes. */\nexport async function azureWrite(ctx: AzureContext, path: string, data: Buffer): Promise<void> {\n  const blob = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));\n  const withData = blob as unknown as {\n    uploadData?: (buffer: Buffer) => Promise<void>;\n    upload?: (buffer: Buffer, length: number) => Promise<void>;\n  };\n  if (typeof withData.uploadData === \"function\") {\n    await withData.uploadData(data);\n    return;\n  }\n  if (typeof withData.upload === \"function\") {\n    await withData.upload(data, data.length);\n    return;\n  }\n  throw new Error(\"Azure Blob client does not support upload\");\n}\n\n/** Delete a blob, treating missing blobs as success. */\nexport async function azureDelete(ctx: AzureContext, path: string): Promise<void> {\n  const blob = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));\n  const withDelete = blob as unknown as {\n    deleteIfExists?: () => Promise<void>;\n    delete?: () => Promise<void>;\n  };\n  if (typeof withDelete.deleteIfExists === \"function\") {\n    await withDelete.deleteIfExists();\n    return;\n  }\n  try {\n    await withDelete.delete?.();\n  } catch (error) {\n    if (!isNotFound(error)) {\n      throw error;\n    }\n  }\n}\n\n/** Check whether a blob exists. */\nexport async function azureExists(ctx: AzureContext, path: string): Promise<boolean> {\n  const blob = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));\n  return await blob.exists();\n}\n\n/** List blob names under a prefix, with the storage prefix stripped. */\nexport async function azureList(ctx: AzureContext, listPrefix: string): Promise<string[]> {\n  const prefix = azureKey(ctx.prefix, listPrefix);\n  const blobs: string[] = [];\n  for await (const item of ctx.container.listBlobsFlat(prefix === \"\" ? undefined : { prefix })) {\n    blobs.push(azureRel(ctx.prefix, item.name));\n  }\n  return blobs;\n}\n"],"mappings":";;;;;;;;AAOA,eAAsB,UAAU,KAAmB,MAA+B;CAChF,MAAM,OAAO,IAAI,UAAU,mBAAmB,SAAS,IAAI,QAAQ,IAAI,CAAC;CACxE,IACE,OAAQ,KAAiE,qBACzE,YAEA,OAAO,MACL,KACA,iBAAiB;CAErB,OAAO,MAAM,gBAAgB,IAAI;AACnC;;AAGA,eAAsB,WAAW,KAAmB,MAAc,MAA6B;CAE7F,MAAM,WADO,IAAI,UAAU,mBAAmB,SAAS,IAAI,QAAQ,IAAI,CACnD;CAIpB,IAAI,OAAO,SAAS,eAAe,YAAY;EAC7C,MAAM,SAAS,WAAW,IAAI;EAC9B;CACF;CACA,IAAI,OAAO,SAAS,WAAW,YAAY;EACzC,MAAM,SAAS,OAAO,MAAM,KAAK,MAAM;EACvC;CACF;CACA,MAAM,IAAI,MAAM,2CAA2C;AAC7D;;AAGA,eAAsB,YAAY,KAAmB,MAA6B;CAEhF,MAAM,aADO,IAAI,UAAU,mBAAmB,SAAS,IAAI,QAAQ,IAAI,CACjD;CAItB,IAAI,OAAO,WAAW,mBAAmB,YAAY;EACnD,MAAM,WAAW,eAAe;EAChC;CACF;CACA,IAAI;EACF,MAAM,WAAW,SAAS;CAC5B,SAAS,OAAO;EACd,IAAI,CAAC,WAAW,KAAK,GACnB,MAAM;CAEV;AACF;;AAGA,eAAsB,YAAY,KAAmB,MAAgC;CAEnF,OAAO,MADM,IAAI,UAAU,mBAAmB,SAAS,IAAI,QAAQ,IAAI,CACvD,CAAC,CAAC,OAAO;AAC3B;;AAGA,eAAsB,UAAU,KAAmB,YAAuC;CACxF,MAAM,SAAS,SAAS,IAAI,QAAQ,UAAU;CAC9C,MAAM,QAAkB,CAAC;CACzB,WAAW,MAAM,QAAQ,IAAI,UAAU,cAAc,WAAW,KAAK,KAAA,IAAY,EAAE,OAAO,CAAC,GACzF,MAAM,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,CAAC;CAE5C,OAAO;AACT"}

package/dist/streams.mjs

@@ -0,0 +1,46 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { collectStream, deleteBlobQuiet } from "./errors.mjs";
+import { azureKey } from "./keys.mjs";
+import { azureExists, azureWrite } from "./operations.mjs";
+import { Readable } from "node:stream";
+//#region src/streams.ts
+/** Streamed Azure blob reads and writes, with failure cleanup. */
+/** Upload a readable, streaming when the SDK supports it and buffering otherwise. */
+async function azureWriteStream(ctx, path, stream) {
+	const blob = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));
+	if (await tryAzureStreamUpload(blob, stream)) return;
+	await writeStreamBuffered(ctx, path, stream, blob);
+}
+/** Download a blob as a readable, rejecting when the blob is missing. */
+async function azureReadStream(ctx, path) {
+	if (!await azureExists(ctx, path)) throw new Error(`No object at "${path}"`);
+	const body = (await ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path)).download()).readableStreamBody;
+	if (!body) return Readable.from([]);
+	return body;
+}
+async function tryAzureStreamUpload(blob, stream) {
+	const withStream = blob;
+	if (typeof withStream.uploadStream !== "function") return false;
+	try {
+		await withStream.uploadStream(stream);
+		return true;
+	} catch (error) {
+		await deleteBlobQuiet(blob);
+		throw error;
+	}
+}
+async function writeStreamBuffered(ctx, path, stream, blob) {
+	try {
+		const data = await collectStream(stream);
+		await azureWrite(ctx, path, data);
+	} catch (error) {
+		await deleteBlobQuiet(blob);
+		throw error;
+	}
+}
+//#endregion
+export { azureReadStream, azureWriteStream };
+
+//# sourceMappingURL=streams.mjs.map

package/dist/streams.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.mjs","names":[],"sources":["../src/streams.ts"],"sourcesContent":["import type { ContainerClient } from \"@azure/storage-blob\";\nimport { Readable } from \"node:stream\";\nimport type { AzureContext } from \"./client.ts\";\nimport { collectStream, deleteBlobQuiet } from \"./errors.ts\";\nimport { azureKey } from \"./keys.ts\";\nimport { azureExists, azureWrite } from \"./operations.ts\";\n\n/** Streamed Azure blob reads and writes, with failure cleanup. */\n\n/** Upload a readable, streaming when the SDK supports it and buffering otherwise. */\nexport async function azureWriteStream(\n  ctx: AzureContext,\n  path: string,\n  stream: Readable,\n): Promise<void> {\n  const blob = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));\n  if (await tryAzureStreamUpload(blob, stream)) {\n    return;\n  }\n  await writeStreamBuffered(ctx, path, stream, blob);\n}\n\n/** Download a blob as a readable, rejecting when the blob is missing. */\nexport async function azureReadStream(ctx: AzureContext, path: string): Promise<Readable> {\n  const exists = await azureExists(ctx, path);\n  if (!exists) {\n    throw new Error(`No object at \"${path}\"`);\n  }\n  const blob = ctx.container.getBlockBlobClient(azureKey(ctx.prefix, path));\n  const response = await blob.download();\n  const body = response.readableStreamBody as unknown as Readable | undefined;\n  if (!body) {\n    return Readable.from([]);\n  }\n  return body;\n}\n\nasync function tryAzureStreamUpload(\n  blob: ReturnType<ContainerClient[\"getBlockBlobClient\"]>,\n  stream: Readable,\n): Promise<boolean> {\n  const withStream = blob as unknown as { uploadStream?: (s: Readable) => Promise<void> };\n  if (typeof withStream.uploadStream !== \"function\") {\n    return false;\n  }\n  try {\n    await withStream.uploadStream(stream);\n    return true;\n  } catch (error) {\n    await deleteBlobQuiet(blob);\n    throw error;\n  }\n}\n\nasync function writeStreamBuffered(\n  ctx: AzureContext,\n  path: string,\n  stream: Readable,\n  blob: ReturnType<ContainerClient[\"getBlockBlobClient\"]>,\n): Promise<void> {\n  try {\n    const data = await collectStream(stream);\n    await azureWrite(ctx, path, data);\n  } catch (error) {\n    await deleteBlobQuiet(blob);\n    throw error;\n  }\n}\n"],"mappings":";;;;;;;;;;AAUA,eAAsB,iBACpB,KACA,MACA,QACe;CACf,MAAM,OAAO,IAAI,UAAU,mBAAmB,SAAS,IAAI,QAAQ,IAAI,CAAC;CACxE,IAAI,MAAM,qBAAqB,MAAM,MAAM,GACzC;CAEF,MAAM,oBAAoB,KAAK,MAAM,QAAQ,IAAI;AACnD;;AAGA,eAAsB,gBAAgB,KAAmB,MAAiC;CAExF,IAAI,CAAC,MADgB,YAAY,KAAK,IAAI,GAExC,MAAM,IAAI,MAAM,iBAAiB,KAAK,EAAE;CAI1C,MAAM,QAAO,MAFA,IAAI,UAAU,mBAAmB,SAAS,IAAI,QAAQ,IAAI,CAC7C,CAAC,CAAC,SAAS,EAAA,CACf;CACtB,IAAI,CAAC,MACH,OAAO,SAAS,KAAK,CAAC,CAAC;CAEzB,OAAO;AACT;AAEA,eAAe,qBACb,MACA,QACkB;CAClB,MAAM,aAAa;CACnB,IAAI,OAAO,WAAW,iBAAiB,YACrC,OAAO;CAET,IAAI;EACF,MAAM,WAAW,aAAa,MAAM;EACpC,OAAO;CACT,SAAS,OAAO;EACd,MAAM,gBAAgB,IAAI;EAC1B,MAAM;CACR;AACF;AAEA,eAAe,oBACb,KACA,MACA,QACA,MACe;CACf,IAAI;EACF,MAAM,OAAO,MAAM,cAAc,MAAM;EACvC,MAAM,WAAW,KAAK,MAAM,IAAI;CAClC,SAAS,OAAO;EACd,MAAM,gBAAgB,IAAI;EAC1B,MAAM;CACR;AACF"}

package/dist/types.d.mts

@@ -0,0 +1,26 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ContainerClient } from "@azure/storage-blob";
+//#region src/types.d.ts
+/** Options for configuring an Azure Blob Storage adapter. */
+interface AzureStorageOptions {
+  /** Azure container name. */
+  container: string;
+  /** Optional blob prefix applied to all stored objects. */
+  prefix?: string;
+  /** Pre-configured container client. */
+  client?: ContainerClient;
+  /** Azure Storage connection string. */
+  connectionString?: string;
+  /** Storage account name. */
+  accountName?: string;
+  /** Storage account key. */
+  accountKey?: string;
+  /** Blob service URL (e.g. https://myaccount.blob.core.windows.net). */
+  accountUrl?: string;
+  /** SAS token (with or without leading `?`). */
+  sasToken?: string;
+}
+//#endregion
+export { AzureStorageOptions };
+//# sourceMappingURL=types.d.mts.map

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@storyshelf/storage-azure",
+  "version": "0.5.3",
+  "description": "Azure Blob Storage adapter for StoryShelf.",
+  "keywords": [
+    "azure",
+    "blob-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-azure"
+  },
+  "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": {
+    "@azure/storage-blob": "^12.26.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
+    }
+  }
+}