Accept a structural Netlify Blobs store

Replace the public SDK class parameter with the methods the adapter
needs.  This prevents bundled private Store declarations from rejecting
real SDK instances and keeps Blobs optional.  Test doubles now work
without an unsafe cast.

Compile the documented SDK usage against the built declarations to
cover the npm consumer API.  Package checks and the Deno, Node.js, and
Bun suites passed; the credentialed integration test was skipped.

Codex assisted with implementation, regression tests, and this commit.

#1029 (comment)

Assisted-by: Codex:gpt-5.6-sol
Assisted-by: Codex:gpt-6-astra

Author: sij411

packages/netlify/fixtures/public-types.ts

@@ -0,0 +1,7 @@
+import { getStore } from "@netlify/blobs";
+import { NetlifyBlobsKvStore } from "../dist/mod.js";
+
+new NetlifyBlobsKvStore(getStore({
+  name: "fedify",
+  consistency: "strong",
+}));

packages/netlify/src/kv.ts

@@ -4,9 +4,9 @@ import type {
   KvStoreListEntry,
   KvStoreSetOptions,
 } from "@fedify/fedify/federation";
-import type { Store } from "@netlify/blobs";
 import { decodeBase64Url, encodeBase64Url } from "byte-encodings/base64url";
 import { isEqual } from "es-toolkit";
+import type { NetlifyBlobsStore } from "./types.ts";
 
 const MAX_BLOB_KEY_BYTES = 600;
 const BLOB_KEY_PREFIX = "fedify1.";
@@ -19,13 +19,13 @@ const textDecoder = new TextDecoder();
  * @since 2.4.0
  */
 export class NetlifyBlobsKvStore implements KvStore {
-  readonly #store: Store;
+  readonly #store: NetlifyBlobsStore;
 
   /**
    * Creates a new Netlify Blobs-backed key-value store.
    * @param store The Netlify Blobs store to use.
    */
-  constructor(store: Store) {
+  constructor(store: NetlifyBlobsStore) {
     this.#store = store;
   }
 

packages/netlify/src/mod.ts

@@ -18,4 +18,7 @@ export {
   NetlifyMessageQueueSendError,
   type NetlifyQueueEventData,
 } from "./mq.ts";
-export type { NetlifyAsyncWorkloadsClient } from "./types.ts";
+export type {
+  NetlifyAsyncWorkloadsClient,
+  NetlifyBlobsStore,
+} from "./types.ts";

packages/netlify/src/types.ts

@@ -1,5 +1,63 @@
 import type { NetlifyQueueEventData } from "./mq.ts";
 
+/**
+ * The subset of Netlify's Blobs `Store` used by this package.
+ *
+ * The real Netlify Blobs `Store` satisfies this interface.  The narrower
+ * interface also keeps Netlify Blobs optional and makes it possible to supply
+ * a test double.
+ *
+ * @since 2.4.0
+ */
+export interface NetlifyBlobsStore {
+  getWithMetadata(
+    key: string,
+    options: {
+      readonly consistency?: "eventual" | "strong";
+      readonly type: "json";
+    },
+  ): Promise<
+    {
+      readonly data: unknown;
+      readonly etag?: string;
+      readonly metadata: Record<string, unknown>;
+    } | null
+  >;
+
+  setJSON(
+    key: string,
+    data: unknown,
+    options?:
+      & {
+        readonly metadata?: Record<string, unknown>;
+      }
+      & (
+        | {
+          readonly onlyIfNew?: boolean;
+          readonly onlyIfMatch?: never;
+        }
+        | {
+          readonly onlyIfMatch?: string;
+          readonly onlyIfNew?: never;
+        }
+      ),
+  ): Promise<{
+    readonly etag?: string;
+    readonly modified: boolean;
+  }>;
+
+  delete(key: string): Promise<void>;
+
+  list(options: {
+    readonly paginate: true;
+    readonly prefix?: string;
+  }): AsyncIterable<{
+    readonly blobs: readonly {
+      readonly key: string;
+    }[];
+  }>;
+}
+
 /**
  * The subset of Netlify's `AsyncWorkloadsClient` used by this package.
  *

packages/netlify/test/kv.test.ts

@@ -2,7 +2,7 @@ import "temporal-polyfill/global";
 import { deepStrictEqual, equal, ok, rejects } from "node:assert/strict";
 import { describe, it } from "node:test";
 import type { KvKey } from "@fedify/fedify/federation";
-import { getStore, type SetOptions, type Store } from "@netlify/blobs";
+import { getStore, type SetOptions } from "@netlify/blobs";
 import { encodeBase64Url } from "byte-encodings/base64url";
 import { NetlifyBlobsKvStore } from "../src/kv.ts";
 
@@ -90,7 +90,7 @@ class MockStore {
 }
 
 function createKv(store: MockStore): NetlifyBlobsKvStore {
-  return new NetlifyBlobsKvStore(store as unknown as Store);
+  return new NetlifyBlobsKvStore(store);
 }
 
 function encodeKey(key: KvKey): string {

packages/netlify/test/package.test.ts

@@ -1,6 +1,11 @@
+import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const canRunTypeScript = !("Deno" in globalThis);
 
 describe("package exports", () => {
   it("loads the ESM distribution", async () => {
@@ -15,4 +20,29 @@ describe("package exports", () => {
     assert.equal(typeof module.NetlifyMessageQueue, "function");
     assert.equal(typeof module.createNetlifyQueueHandler, "function");
   });
+
+  it("accepts the Netlify Blobs Store in the public types", {
+    skip: !canRunTypeScript,
+  }, () => {
+    const require = createRequire(import.meta.url);
+    const tsc = require.resolve("typescript/bin/tsc");
+    const fixture = fileURLToPath(
+      new URL("../fixtures/public-types.ts", import.meta.url),
+    );
+
+    execFileSync(process.execPath, [
+      tsc,
+      "--noEmit",
+      "--strict",
+      "--types",
+      "node",
+      "--module",
+      "NodeNext",
+      "--moduleResolution",
+      "NodeNext",
+      "--target",
+      "ESNext",
+      fixture,
+    ]);
+  });
 });