feat: support signed urls

Author: rdunk

package.json

@@ -9,6 +9,11 @@
       "import": "./lib/index.js",
       "default": "./lib/index.js"
     },
+    "./signed": {
+      "source": "./src/signed/index.ts",
+      "import": "./lib/signed/index.js",
+      "default": "./lib/signed/index.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./lib/index.js",
@@ -79,5 +84,8 @@
     "content",
     "image-url"
   ],
+  "dependencies": {
+    "@sanity/signed-urls": "^2.0.0"
+  },
   "packageManager": "[email protected]"
 }

pnpm-lock.yaml

@@ -29,7 +29,10 @@ function isSanityClientLike(
   return client && 'clientConfig' in client ? typeof client.clientConfig === 'object' : false
 }
 
-function rewriteSpecName(key: string) {
+/**
+ * @internal
+ */
+export function rewriteSpecName(key: string) {
   const specs = SPEC_NAME_TO_URL_NAME_MAPPINGS
   for (const entry of specs) {
     const [specName, param] = entry
@@ -42,37 +45,52 @@ function rewriteSpecName(key: string) {
 }
 
 /**
- * @public
+ * @internal
  */
-export function createImageUrlBuilder(
-  options?: SanityClientLike | SanityProjectDetails | SanityModernClientLike
-) {
-  // Did we get a modernish client?
-  if (isSanityModernClientLike(options)) {
+export function createBuilder<C extends typeof ImageUrlBuilder>(
+  Builder: C,
+  _options?: SanityClientLike | SanityProjectDetails | SanityModernClientLike
+): InstanceType<C> {
+  let options: ConstructorParameters<C>[1] = {}
+
+  if (isSanityModernClientLike(_options)) {
     // Inherit config from client
-    const {apiHost: apiUrl, projectId, dataset} = options.config()
+    const {apiHost: apiUrl, projectId, dataset} = _options.config()
     const apiHost = apiUrl || 'https://api.sanity.io'
-    return new ImageUrlBuilder(null, {
+    options = {
       baseUrl: apiHost.replace(/^https:\/\/api\./, 'https://cdn.'),
       projectId,
       dataset,
-    })
+    }
   }
 
   // Did we get a SanityClient?
-  if (isSanityClientLike(options)) {
+  else if (isSanityClientLike(_options)) {
     // Inherit config from client
-    const {apiHost: apiUrl, projectId, dataset} = options.clientConfig
+    const {apiHost: apiUrl, projectId, dataset} = _options.clientConfig
     const apiHost = apiUrl || 'https://api.sanity.io'
-    return new ImageUrlBuilder(null, {
+    options = {
       baseUrl: apiHost.replace(/^https:\/\/api\./, 'https://cdn.'),
       projectId,
       dataset,
-    })
+    }
   }
 
   // Or just accept the options as given
-  return new ImageUrlBuilder(null, options || {})
+  else {
+    options = _options || {}
+  }
+
+  return new Builder(null, options) as InstanceType<C>
+}
+
+/**
+ * @public
+ */
+export function createImageUrlBuilder(
+  options?: SanityClientLike | SanityProjectDetails | SanityModernClientLike
+) {
+  return createBuilder(ImageUrlBuilder, options)
 }
 
 /**
@@ -87,7 +105,7 @@ export class ImageUrlBuilder {
       : {...(options || {})} // Copy options
   }
 
-  withOptions(options: Partial<ImageUrlBuilderOptionsWithAliases>) {
+  protected constructNewOptions(options: Partial<ImageUrlBuilderOptionsWithAliases>) {
     const baseUrl = options.baseUrl || this.options.baseUrl
 
     const newOptions: {[key: string]: any} = {baseUrl}
@@ -97,8 +115,12 @@ export class ImageUrlBuilder {
         newOptions[specKey] = options[key]
       }
     }
+    return {baseUrl, ...newOptions}
+  }
 
-    return new ImageUrlBuilder(this, {baseUrl, ...newOptions})
+  withOptions(options: Partial<ImageUrlBuilderOptionsWithAliases>): this {
+    const newOptions = this.constructNewOptions(options)
+    return new ImageUrlBuilder(this, newOptions) as this
   }
 
   // The image to be represented. Accepts a Sanity 'image'-document, 'asset'-document or

src/builder.ts

@@ -0,0 +1,29 @@
+export {createImageUrlBuilder} from './signed-builder'
+
+export type {
+  AutoMode,
+  CropMode,
+  CropSpec,
+  FitMode,
+  HotspotSpec,
+  ImageFormat,
+  ImageUrlBuilderOptions,
+  ImageUrlBuilderOptionsWithAliases,
+  ImageUrlBuilderOptionsWithAsset,
+  Orientation,
+  SanityAsset,
+  SanityClientLike,
+  SanityImageCrop,
+  SanityImageDimensions,
+  SanityImageFitResult,
+  SanityImageHotspot,
+  SanityImageObject,
+  SanityImageRect,
+  SanityImageSource,
+  SanityImageWithAssetStub,
+  SanityModernClientLike,
+  SanityProjectDetails,
+  SanityReference,
+} from '../types'
+
+export type {ImageUrlSigningOptions, ImageUrlSignedBuilderOptions} from './types'

src/signed/index.ts

@@ -0,0 +1,64 @@
+import {createBuilder, ImageUrlBuilder} from '../builder'
+import {signedUrlForImage} from './signedUrlForImage'
+import type {ImageUrlSignedBuilderOptions, ImageUrlSigningOptions} from './types'
+import type {
+  ImageUrlBuilderOptions,
+  ImageUrlBuilderOptionsWithAliases,
+  SanityClientLike,
+  SanityModernClientLike,
+  SanityProjectDetails,
+} from '../types'
+
+function assertValidSignedOptions(
+  opts: Partial<ImageUrlSigningOptions>
+): asserts opts is ImageUrlSigningOptions {
+  if (typeof opts.keyId !== 'string') {
+    throw new Error('Cannot call `signedUrl()` without `keyId`')
+  }
+
+  if (typeof opts.privateKey !== 'string') {
+    throw new Error('Cannot call `signedUrl()` without `privateKey`')
+  }
+}
+
+/**
+ * @internal
+ */
+export class ImageSignedUrlBuilder extends ImageUrlBuilder {
+  public declare options: ImageUrlBuilderOptions & Partial<ImageUrlSigningOptions>
+
+  constructor(parent: ImageSignedUrlBuilder | null, options: ImageUrlSignedBuilderOptions) {
+    super(parent, options)
+  }
+
+  override withOptions(
+    options: Partial<ImageUrlBuilderOptionsWithAliases & ImageUrlSigningOptions>
+  ): this {
+    const newOptions = this.constructNewOptions(options)
+    return new ImageSignedUrlBuilder(this, {...newOptions}) as this
+  }
+
+  expiry(expiry: string | Date) {
+    return this.withOptions({expiry})
+  }
+
+  signingKey(keyId: string, privateKey: string) {
+    return this.withOptions({keyId, privateKey})
+  }
+
+  signedUrl() {
+    const {expiry, keyId, privateKey, ...rest} = this.options
+    const signedOptions = {expiry, keyId, privateKey}
+    assertValidSignedOptions(signedOptions)
+    return signedUrlForImage(rest, signedOptions)
+  }
+}
+
+/**
+ * @public
+ */
+export function createImageUrlBuilder(
+  options?: SanityClientLike | SanityProjectDetails | SanityModernClientLike
+) {
+  return createBuilder(ImageSignedUrlBuilder, options)
+}

src/signed/signed-builder.ts

@@ -0,0 +1,14 @@
+import {signUrl} from '@sanity/signed-urls'
+import type {ImageUrlBuilderOptions} from '../types'
+import type {ImageUrlSigningOptions} from './types'
+import {urlForImage} from '../urlForImage'
+
+export function signedUrlForImage(
+  options: ImageUrlBuilderOptions,
+  signingOptions: ImageUrlSigningOptions
+): string {
+  // Get the base URL without any signing specific parameters
+  const baseUrl = urlForImage(options)
+  // Sign the URL with the signing parameters
+  return signUrl(baseUrl, signingOptions)
+}

src/signed/signedUrlForImage.ts

@@ -0,0 +1,15 @@
+import type {ImageUrlBuilderOptions} from '../types'
+
+/**
+ * @public
+ */
+export interface ImageUrlSigningOptions {
+  keyId: string
+  privateKey: string
+  expiry?: string | Date
+}
+
+/**
+ * @public
+ */
+export type ImageUrlSignedBuilderOptions = ImageUrlBuilderOptions & Partial<ImageUrlSigningOptions>