feat!: add listStores method

BREAKING CHANGE: Site-scoped created with previous versions of the client will not be accessible.

Author: eduardoboucas

.eslintrc.cjs

@@ -23,6 +23,7 @@ module.exports = {
     'unicorn/prefer-ternary': 'off',
     'no-unused-vars': 'off',
     '@typescript-eslint/no-unused-vars': ['error', { ignoreRestSiblings: true }],
+    'func-style': 'off',
   },
   overrides: [
     ...overrides,

src/backend/list_stores.ts

@@ -0,0 +1,4 @@
+export interface ListStoresResponse {
+  stores: string[]
+  next_cursor?: string
+}

src/client.ts

@@ -12,7 +12,7 @@ interface MakeStoreRequestOptions {
   metadata?: Metadata
   method: HTTPMethod
   parameters?: Record<string, string>
-  storeName: string
+  storeName?: string
 }
 
 export interface ClientOptions {
@@ -31,7 +31,7 @@ interface GetFinalRequestOptions {
   metadata?: Metadata
   method: string
   parameters?: Record<string, string>
-  storeName: string
+  storeName?: string
 }
 
 export class Client {
@@ -70,6 +70,16 @@ export class Client {
     const encodedMetadata = encodeMetadata(metadata)
     const consistency = opConsistency ?? this.consistency
 
+    let urlPath = `/${this.siteID}`
+
+    if (storeName) {
+      urlPath += `/${storeName}`
+    }
+
+    if (key) {
+      urlPath += `/${key}`
+    }
+
     if (this.edgeURL) {
       if (consistency === 'strong' && !this.uncachedEdgeURL) {
         throw new BlobsConsistencyError()
@@ -83,8 +93,7 @@ export class Client {
         headers[METADATA_HEADER_INTERNAL] = encodedMetadata
       }
 
-      const path = key ? `/${this.siteID}/${storeName}/${key}` : `/${this.siteID}/${storeName}`
-      const url = new URL(path, consistency === 'strong' ? this.uncachedEdgeURL : this.edgeURL)
+      const url = new URL(urlPath, consistency === 'strong' ? this.uncachedEdgeURL : this.edgeURL)
 
       for (const key in parameters) {
         url.searchParams.set(key, parameters[key])
@@ -97,23 +106,22 @@ export class Client {
     }
 
     const apiHeaders: Record<string, string> = { authorization: `Bearer ${this.token}` }
-    const url = new URL(`/api/v1/blobs/${this.siteID}/${storeName}`, this.apiURL ?? 'https://api.netlify.com')
+    const url = new URL(`/api/v1/blobs${urlPath}`, this.apiURL ?? 'https://api.netlify.com')
 
     for (const key in parameters) {
       url.searchParams.set(key, parameters[key])
     }
 
-    // If there is no key, we're dealing with the list endpoint, which is
-    // implemented directly in the Netlify API.
-    if (key === undefined) {
+    // If there is no store name, we're listing stores. If there's no key,
+    // we're listing blobs. Both operations are implemented directly in the
+    // Netlify API.
+    if (storeName === undefined || key === undefined) {
       return {
         headers: apiHeaders,
         url: url.toString(),
       }
     }
 
-    url.pathname += `/${key}`
-
     if (encodedMetadata) {
       apiHeaders[METADATA_HEADER_EXTERNAL] = encodedMetadata
     }

src/main.ts

@@ -1,4 +1,5 @@
 export { getDeployStore, getStore } from './store_factory.ts'
+export { listStores } from './store_list.ts'
 export { BlobsServer } from './server.ts'
 export type {
   Store,

src/store.ts

@@ -7,6 +7,9 @@ import { getMetadataFromResponse, Metadata } from './metadata.ts'
 import { BlobInput, HTTPMethod } from './types.ts'
 import { BlobsInternalError, collectIterator } from './util.ts'
 
+export const DEPLOY_STORE_PREFIX = 'deploy:'
+export const SITE_STORE_PREFIX = 'site:'
+
 interface BaseStoreOptions {
   client: Client
   consistency?: ConsistencyMode
@@ -64,21 +67,19 @@ export type BlobResponseType = 'arrayBuffer' | 'blob' | 'json' | 'stream' | 'tex
 
 export class Store {
   private client: Client
-  private consistency: ConsistencyMode
   private name: string
 
   constructor(options: StoreOptions) {
     this.client = options.client
-    this.consistency = options.consistency ?? 'eventual'
 
     if ('deployID' in options) {
       Store.validateDeployID(options.deployID)
 
-      this.name = `deploy:${options.deployID}`
+      this.name = DEPLOY_STORE_PREFIX + options.deployID
     } else {
       Store.validateStoreName(options.name)
 
-      this.name = options.name
+      this.name = SITE_STORE_PREFIX + options.name
     }
   }
 
@@ -349,10 +350,6 @@ export class Store {
   }
 
   private static validateStoreName(name: string) {
-    if (name.startsWith('deploy:') || name.startsWith('deploy%3A1')) {
-      throw new Error('Store name must not start with the `deploy:` reserved keyword.')
-    }
-
     if (name.includes('/') || name.includes('%2F')) {
       throw new Error('Store name must not contain forward slashes (/).')
     }