@panorama-industries/effect-vercel-blob 0.0.0-stage → 0.2.0

package/src/contracts/blob-errors.ts

@@ -0,0 +1,161 @@
+import { Schema } from "effect";
+
+/** The blob does not exist (`not_found`). */
+export class BlobNotFound extends Schema.TaggedError<BlobNotFound>()("BlobNotFound", {
+  /** The pathname or URL that was requested. */
+  locator: Schema.String,
+}) {}
+
+/** The store addressed by the credentials does not exist (`store_not_found`). */
+export class BlobStoreNotFound extends Schema.TaggedError<BlobStoreNotFound>()(
+  "BlobStoreNotFound",
+  {},
+) {}
+
+/** The store has been suspended, for example for exceeding the Hobby quota (`store_suspended`). */
+export class BlobStoreSuspended extends Schema.TaggedError<BlobStoreSuspended>()(
+  "BlobStoreSuspended",
+  {},
+) {}
+
+/** The store cannot serve any request. */
+export class BlobStoreUnavailable extends Schema.TaggedError<BlobStoreUnavailable>()(
+  "BlobStoreUnavailable",
+  {
+    reason: Schema.Union([BlobStoreNotFound, BlobStoreSuspended]),
+  },
+) {}
+
+/** A conditional write or delete found a different ETag than `ifMatch` (`precondition_failed`). */
+export class BlobPreconditionFailed extends Schema.TaggedError<BlobPreconditionFailed>()(
+  "BlobPreconditionFailed",
+  {},
+) {}
+
+/** The upload's media type is not among the token's `allowedContentTypes`. */
+export class ContentTypeNotAllowed extends Schema.TaggedError<ContentTypeNotAllowed>()(
+  "ContentTypeNotAllowed",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/** The upload is larger than `maximumSizeInBytes`, checked locally or by the store. */
+export class FileTooLarge extends Schema.TaggedError<FileTooLarge>()("FileTooLarge", {
+  message: Schema.String,
+}) {}
+
+/** The upload's pathname differs from the one the client token was issued for. */
+export class PathnameMismatch extends Schema.TaggedError<PathnameMismatch>()("PathnameMismatch", {
+  message: Schema.String,
+}) {}
+
+/** The client token's `validUntil` has passed. */
+export class ClientTokenExpired extends Schema.TaggedError<ClientTokenExpired>()(
+  "ClientTokenExpired",
+  {},
+) {}
+
+/** The store refused an upload because it breaks a constraint of its token. */
+export class BlobUploadRejected extends Schema.TaggedError<BlobUploadRejected>()(
+  "BlobUploadRejected",
+  {
+    reason: Schema.Union([
+      ContentTypeNotAllowed,
+      FileTooLarge,
+      PathnameMismatch,
+      ClientTokenExpired,
+    ]),
+  },
+) {}
+
+/**
+ * The operation needs a read-write or OIDC token and was called with a client token
+ * (`client_token_not_allowed`), such as `rename`.
+ */
+export class BlobClientTokenNotAllowed extends Schema.TaggedError<BlobClientTokenNotAllowed>()(
+  "BlobClientTokenNotAllowed",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/**
+ * The project enables OIDC for Blob but not for the environment the token was issued in
+ * (`oidc_environment_not_allowed`). Enable it in the store's settings or use a read-write token.
+ */
+export class BlobOidcEnvironmentNotAllowed extends Schema.TaggedError<BlobOidcEnvironmentNotAllowed>()(
+  "BlobOidcEnvironmentNotAllowed",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/**
+ * The operation signs with the store's read-write token, and none is configured. OIDC is not
+ * enough for client tokens and their callbacks; set `BLOB_READ_WRITE_TOKEN`.
+ */
+export class BlobReadWriteTokenRequired extends Schema.TaggedError<BlobReadWriteTokenRequired>()(
+  "BlobReadWriteTokenRequired",
+  {
+    operation: Schema.String,
+  },
+) {}
+
+/** A presigned URL could not be signed: the token's scope or the options do not allow it. */
+export class BlobPresignFailed extends Schema.TaggedError<BlobPresignFailed>()(
+  "BlobPresignFailed",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/** The `x-vercel-signature` header is absent. */
+export class SignatureMissing extends Schema.TaggedError<SignatureMissing>()(
+  "SignatureMissing",
+  {},
+) {}
+
+/** The `x-vercel-signature` header does not match the body. */
+export class SignatureInvalid extends Schema.TaggedError<SignatureInvalid>()(
+  "SignatureInvalid",
+  {},
+) {}
+
+/** The request body is not a known upload event, or not JSON. */
+export class EventMalformed extends Schema.TaggedError<EventMalformed>()("EventMalformed", {
+  message: Schema.String,
+}) {}
+
+/** The presigned flow has no webhook public key: set `BLOB_WEBHOOK_PUBLIC_KEY`. */
+export class WebhookPublicKeyMissing extends Schema.TaggedError<WebhookPublicKeyMissing>()(
+  "WebhookPublicKeyMissing",
+  {},
+) {}
+
+/**
+ * An upload route received a request it must refuse. Respond with a 4xx: the blob store retries an
+ * upload-completed callback that does not get a 200.
+ */
+export class BlobUploadEventRejected extends Schema.TaggedError<BlobUploadEventRejected>()(
+  "BlobUploadEventRejected",
+  {
+    reason: Schema.Union([
+      SignatureMissing,
+      SignatureInvalid,
+      EventMalformed,
+      WebhookPublicKeyMissing,
+    ]),
+  },
+) {}
+
+/** The browser could not get a client token or presigned URL from the upload route. */
+export class BlobUploadAuthorizationFailed extends Schema.TaggedError<BlobUploadAuthorizationFailed>()(
+  "BlobUploadAuthorizationFailed",
+  {
+    /** The route's status code; none when the request failed before a response. */
+    status: Schema.Option(Schema.Int),
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {}

package/src/contracts/blob-signed-urls.ts

@@ -0,0 +1,112 @@
+import type { Array, DateTime, Effect } from "effect";
+
+import { Context } from "effect";
+
+import type {
+  BlobAccess,
+  DelegationOperation,
+  ETag,
+  PresignedUrlPayload,
+  SignedToken,
+} from "./blob-domain.ts";
+import type { BlobPresignFailed } from "./blob-errors.ts";
+import type { BlobRequestError } from "./blob-store.ts";
+
+/** Scope of a signed token. Every field narrows what presigned URLs signed from it may do. */
+export interface IssueSignedTokenOptions {
+  /** Pathname the token covers; `*` or omitted covers the whole store. */
+  readonly pathname?: string | undefined;
+
+  /** Operations the token delegates; the store defaults to `get`. Duplicates are removed. */
+  readonly operations?: Array.NonEmptyReadonlyArray<DelegationOperation> | undefined;
+
+  /** Expiry, in the future and at most 7 days away; the store defaults to one hour. */
+  readonly validUntil?: DateTime.Utc | undefined;
+
+  /** Largest upload a presigned `put` may send. */
+  readonly maximumSizeInBytes?: number | undefined;
+
+  /** Media types a presigned `put` may upload; wildcards such as `image/*` are allowed. */
+  readonly allowedContentTypes?: ReadonlyArray<string> | undefined;
+}
+
+/** Callback the store calls after a presigned upload completes. */
+export interface PresignUploadCompleted {
+  /** Absolute URL of the route that handles `blob.upload-completed`. */
+  readonly callbackUrl: string;
+
+  /** Data passed back to the callback, such as the uploading user's id. */
+  readonly tokenPayload?: string | undefined;
+}
+
+/** What one presigned URL authorizes. Constraints may only narrow the signed token's. */
+export type PresignOptions =
+  | {
+      readonly operation: "get";
+      readonly pathname: string;
+      /** Earlier expiry than the token's. */
+      readonly validUntil?: DateTime.Utc | undefined;
+      /** Add `cache=0` to read a private blob from origin storage; not signed. */
+      readonly useCache?: boolean | undefined;
+    }
+  | {
+      readonly operation: "head";
+      readonly pathname: string;
+      readonly validUntil?: DateTime.Utc | undefined;
+    }
+  | {
+      readonly operation: "put";
+      readonly pathname: string;
+      readonly validUntil?: DateTime.Utc | undefined;
+      readonly allowedContentTypes?: ReadonlyArray<string> | undefined;
+      readonly maximumSizeInBytes?: number | undefined;
+      readonly onUploadCompleted?: PresignUploadCompleted | undefined;
+      readonly allowOverwrite?: boolean | undefined;
+      readonly addRandomSuffix?: boolean | undefined;
+      /** In seconds, at most one year. */
+      readonly cacheControlMaxAge?: number | undefined;
+      readonly ifMatch?: ETag | undefined;
+    }
+  | {
+      readonly operation: "delete";
+      readonly pathname: string;
+      readonly validUntil?: DateTime.Utc | undefined;
+      readonly ifMatch?: ETag | undefined;
+    };
+
+/** The secret and public halves of a signed token, as needed to presign. */
+export type SigningToken = Pick<SignedToken, "delegationToken" | "clientSigningToken">;
+
+/**
+ * Signed URLs: delegate one operation on one pathname to a holder of a URL, without credentials.
+ *
+ * Issue a {@link SignedToken} once (one API call) and cache it until shortly before it expires;
+ * presigning is local HMAC-SHA256 signing.
+ */
+export class BlobSignedUrls extends Context.Service<
+  BlobSignedUrls,
+  {
+    /** Ask the store for a signed token (`POST /signed-token`). */
+    readonly issueSignedToken: (
+      options?: IssueSignedTokenOptions,
+    ) => Effect.Effect<SignedToken, BlobRequestError>;
+
+    /**
+     * Sign one request. Fails with `BlobPresignFailed` when the token has expired, does not delegate
+     * the operation, covers another pathname, or allows less than the options ask for.
+     */
+    readonly presign: (
+      token: SigningToken,
+      options: PresignOptions,
+    ) => Effect.Effect<PresignedUrlPayload, BlobPresignFailed>;
+
+    /**
+     * Sign one request and build its URL: the blob URL for `get` and `head`, the Blob API URL for
+     * `put` and `delete`.
+     */
+    readonly presignUrl: (
+      token: SigningToken,
+      options: PresignOptions & { readonly access: BlobAccess },
+    ) => Effect.Effect<URL, BlobPresignFailed>;
+  }
+>()("@effect-vercel/blob/BlobSignedUrls") {}

package/src/contracts/blob-store.ts

@@ -0,0 +1,258 @@
+import type { OidcTokenUnavailable, VercelApiError } from "@panorama-industries/effect-vercel-core";
+import type { Array, Duration, Effect, Stream } from "effect";
+
+import { Context, Schema } from "effect";
+
+import type {
+  BlobAccess,
+  BlobBody,
+  BlobLocator,
+  BlobMetadata,
+  BlobPathname,
+  CreateBlobOptions,
+  CreateFolderResult,
+  ETag,
+  GetBlobResult,
+  ListedBlob,
+  ListPage,
+  MultipartUpload,
+  OnUploadProgress,
+  OverwriteOptions,
+  PartNumber,
+  PutBlobResult,
+  UploadedPart,
+} from "./blob-domain.ts";
+import type {
+  BlobNotFound,
+  BlobOidcEnvironmentNotAllowed,
+  BlobPreconditionFailed,
+  BlobStoreUnavailable,
+  BlobUploadRejected,
+} from "./blob-errors.ts";
+
+/** Failures every Blob API call can report. */
+export type BlobRequestError =
+  | VercelApiError
+  | BlobStoreUnavailable
+  | BlobOidcEnvironmentNotAllowed
+  | OidcTokenUnavailable;
+
+/** Failures of creating or replacing a blob. */
+export type BlobWriteError = BlobRequestError | BlobPreconditionFailed | BlobUploadRejected;
+
+/** Options for {@link BlobStore} `put`. */
+export type PutOptions = CreateBlobOptions & {
+  /**
+   * Upload in 8 MiB parts, eight at a time, instead of one request. Use it for large bodies; parts
+   * are produced from the body as it streams, so memory stays bounded.
+   */
+  readonly multipart?: boolean | undefined;
+
+  /**
+   * Refuse a multipart upload whose known size exceeds this many bytes before sending anything.
+   * Streams of unknown size are not checked.
+   */
+  readonly maximumSizeInBytes?: number | undefined;
+
+  readonly onUploadProgress?: OnUploadProgress | undefined;
+};
+
+/** Width of an optimized image in pixels: an integer from 1 to 8192. */
+export const ImageWidth = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 8192 })).pipe(
+  Schema.brand("ImageWidth"),
+);
+
+/** Width of an optimized image in pixels. */
+export type ImageWidth = typeof ImageWidth.Type;
+
+/** Quality of an optimized image: an integer from 1 to 100. */
+export const ImageQuality = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 })).pipe(
+  Schema.brand("ImageQuality"),
+);
+
+/** Quality of an optimized image: an integer from 1 to 100. */
+export type ImageQuality = typeof ImageQuality.Type;
+
+/** Output format of an optimized image. */
+export const ImageFormat = Schema.Literals(["jpeg", "png", "webp", "avif"]);
+
+/** Output format of an optimized image. */
+export type ImageFormat = typeof ImageFormat.Type;
+
+/** How Vercel Image Optimization transforms an image before it is stored. */
+export interface ImageOptimization {
+  readonly width: ImageWidth;
+
+  /** Defaults to 75. */
+  readonly quality?: ImageQuality | undefined;
+
+  /** Defaults to the source format. */
+  readonly format?: ImageFormat | undefined;
+}
+
+/** Options for {@link BlobStore} `putImage`; the stored media type comes from the optimizer. */
+export type PutImageOptions = OverwriteOptions & {
+  readonly access: BlobAccess;
+  readonly addRandomSuffix?: boolean | undefined;
+  readonly cacheControlMaxAge?: Duration.Input | undefined;
+  readonly optimizeImage: ImageOptimization;
+  readonly onUploadProgress?: OnUploadProgress | undefined;
+};
+
+/** Options for {@link BlobStore} `get`. */
+export interface GetOptions {
+  readonly access: BlobAccess;
+
+  /**
+   * When false, read a private blob from origin storage instead of the CDN cache: always the latest
+   * content, but slower. Ignored for public blobs.
+   */
+  readonly useCache?: boolean | undefined;
+
+  /** Return `NotModified` instead of the content when the blob still has this ETag. */
+  readonly ifNoneMatch?: string | undefined;
+
+  /** Extra request headers; they override the defaults, including `authorization`. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+}
+
+/** Options for {@link BlobStore} `list` and `listAll`. */
+export interface ListOptions {
+  /** Entries per page; the store's default and maximum is 1000. */
+  readonly limit?: number | undefined;
+
+  /** Only blobs whose pathname starts with this. */
+  readonly prefix?: string | undefined;
+
+  /**
+   * `folded` returns the folders directly under `prefix` in `folders` and only the blobs at that
+   * level in `blobs`.
+   */
+  readonly mode?: "expanded" | "folded" | undefined;
+}
+
+/** Options for {@link BlobStore} `createMultipartUpload`. */
+export type CreateMultipartUploadOptions = CreateBlobOptions;
+
+/**
+ * The Vercel Blob server API: upload, read, list, copy, rename and delete blobs in one store.
+ *
+ * Credentials and endpoints come from `BlobConfig`.
+ */
+export class BlobStore extends Context.Service<
+  BlobStore,
+  {
+    /**
+     * Store a blob at `pathname`. The store refuses an existing pathname unless `allowOverwrite`
+     * or `ifMatch` is set; `ifMatch` fails with `BlobPreconditionFailed` when the blob has a
+     * different ETag or does not exist. `access` must be the store's.
+     */
+    readonly put: <E = never, R = never>(
+      pathname: BlobPathname,
+      body: BlobBody<E, R>,
+      options: PutOptions,
+    ) => Effect.Effect<PutBlobResult, BlobWriteError | E, R>;
+
+    /**
+     * Optimize an image with Vercel Image Optimization and store only the result. The source is
+     * the image content, or a `URL` the store fetches itself. Requires OIDC credentials. A source
+     * whose known media type is not an image fails with `BlobUploadRejected` before any request.
+     */
+    readonly putImage: <E = never, R = never>(
+      pathname: BlobPathname,
+      source: BlobBody<E, R> | URL,
+      options: PutImageOptions,
+    ) => Effect.Effect<PutBlobResult, BlobWriteError | E, R>;
+
+    /** Read a blob's metadata without its content. */
+    readonly head: (
+      blob: BlobLocator,
+    ) => Effect.Effect<BlobMetadata, BlobRequestError | BlobNotFound>;
+
+    /**
+     * Read a blob's content from its store's host. A pathname is resolved against the configured
+     * store; a URL must point at a Blob store (or the configured API origin, for emulators).
+     */
+    readonly get: (
+      blob: BlobLocator,
+      options: GetOptions,
+    ) => Effect.Effect<GetBlobResult, BlobRequestError | BlobNotFound>;
+
+    /** Read one page of blobs. */
+    readonly list: (
+      options?: ListOptions & { readonly cursor?: string | undefined },
+    ) => Effect.Effect<ListPage, BlobRequestError>;
+
+    /** Every blob matching `options`, fetching pages as the stream is read. */
+    readonly listAll: (options?: ListOptions) => Stream.Stream<ListedBlob, BlobRequestError>;
+
+    /**
+     * Delete a blob. Deleting a missing blob succeeds; with `ifMatch`, a different ETag or a
+     * missing blob fails with `BlobPreconditionFailed`. CDN caches may serve the blob for up to a
+     * minute afterwards.
+     */
+    readonly del: (
+      blob: BlobLocator,
+      options?: { readonly ifMatch?: ETag | undefined },
+    ) => Effect.Effect<void, BlobRequestError | BlobPreconditionFailed>;
+
+    /** Delete several blobs in one request; each counts as one operation for rate limits. */
+    readonly delMany: (
+      blobs: Array.NonEmptyReadonlyArray<BlobLocator>,
+    ) => Effect.Effect<void, BlobRequestError>;
+
+    /**
+     * Copy a blob to `to`. The copy does not inherit the source's media type or cache lifetime;
+     * pass them again. `ifMatch` is checked against the source. The store replaces a blob at `to`
+     * even when `allowOverwrite` is false. A missing source fails with `BlobNotFound`.
+     */
+    readonly copy: (
+      from: BlobLocator,
+      to: BlobPathname,
+      options: CreateBlobOptions,
+    ) => Effect.Effect<PutBlobResult, BlobWriteError | BlobNotFound>;
+
+    /**
+     * Move a blob to `to`: copied, then the source deleted. Unlike `copy`, an existing `to` is
+     * refused unless `allowOverwrite` is set, so if the delete fails the blob exists at both
+     * pathnames; retry with `allowOverwrite: true`. A missing source fails with `BlobNotFound`.
+     */
+    readonly rename: (
+      from: BlobLocator,
+      to: BlobPathname,
+      options: CreateBlobOptions,
+    ) => Effect.Effect<PutBlobResult, BlobWriteError | BlobNotFound>;
+
+    /**
+     * Create an empty folder marker; a trailing `/` is added when missing. An existing folder is
+     * refused. `access` defaults to `public`, which a private store refuses.
+     */
+    readonly createFolder: (
+      pathname: BlobPathname,
+      options?: { readonly access?: BlobAccess | undefined },
+    ) => Effect.Effect<CreateFolderResult, BlobWriteError>;
+
+    /**
+     * Start a multipart upload to control part sizes and concurrency yourself. Parts must be at
+     * least 5 MB except the last, and should all have the same size. `addRandomSuffix` defaults
+     * to true here.
+     */
+    readonly createMultipartUpload: (
+      pathname: BlobPathname,
+      options: CreateMultipartUploadOptions,
+    ) => Effect.Effect<MultipartUpload, BlobWriteError>;
+
+    /** Upload one part of a multipart upload. */
+    readonly uploadPart: <E = never, R = never>(
+      upload: MultipartUpload,
+      partNumber: PartNumber,
+      body: BlobBody<E, R>,
+    ) => Effect.Effect<UploadedPart, BlobWriteError | E, R>;
+
+    /** Assemble the uploaded parts into the blob. */
+    readonly completeMultipartUpload: (
+      upload: MultipartUpload,
+      parts: Array.NonEmptyReadonlyArray<UploadedPart>,
+    ) => Effect.Effect<PutBlobResult, BlobWriteError>;
+  }
+>()("@effect-vercel/blob/BlobStore") {}

package/src/contracts/blob-uploads.ts

@@ -0,0 +1,151 @@
+import type { Effect } from "effect";
+import type { HttpServerRequest, HttpServerResponse } from "effect/http";
+
+import { Context } from "effect";
+
+import type {
+  ClientToken,
+  ClientTokenConstraints,
+  UploadCompleted,
+  UploadRequest,
+} from "./blob-domain.ts";
+import type {
+  BlobPresignFailed,
+  BlobReadWriteTokenRequired,
+  BlobUploadEventRejected,
+} from "./blob-errors.ts";
+import type { PresignOptions, SigningToken } from "./blob-signed-urls.ts";
+
+/** Callback the store calls after a browser upload completes. */
+export interface UploadCompletedCallback {
+  /** Absolute URL of the route that handles `blob.upload-completed`. */
+  readonly callbackUrl: string;
+
+  /** Data passed back to the callback, such as the uploading user's id. */
+  readonly tokenPayload?: string | undefined;
+}
+
+/** Everything a client token encodes. */
+export type ClientTokenOptions = ClientTokenConstraints & {
+  /** The only pathname the token may upload to. */
+  readonly pathname: string;
+
+  readonly onUploadCompleted?: UploadCompletedCallback | undefined;
+};
+
+/** What an upload route allows for one browser upload; returned by `onBeforeGenerateToken`. */
+export type UploadAuthorization = ClientTokenConstraints & {
+  /** Passed to `onUploadCompleted`; defaults to the browser's `clientPayload`. */
+  readonly tokenPayload?: string | undefined;
+
+  /**
+   * Where the upload-completed callback goes. Derived from the environment when omitted:
+   * `VERCEL_BLOB_CALLBACK_URL`, else the preview or production URL on Vercel, plus this route's
+   * path. Never taken from the browser.
+   */
+  readonly callbackUrl?: string | undefined;
+};
+
+/** Hooks of a client-token upload route. */
+export interface UploadHandlerOptions<E, R, E2, R2> {
+  /**
+   * Authenticate and authorize the user, then constrain the upload. Fail to refuse it; the error
+   * leaves the handler so the route can answer 401 or 403.
+   */
+  readonly onBeforeGenerateToken: (
+    request: UploadRequest,
+  ) => Effect.Effect<UploadAuthorization, E, R>;
+
+  /**
+   * Runs when the store reports the upload finished, after the callback's signature is verified.
+   * Without it no callback is requested. Fail to make the store retry the callback.
+   */
+  readonly onUploadCompleted?:
+    | ((event: UploadCompleted) => Effect.Effect<void, E2, R2>)
+    | undefined;
+}
+
+/** What a presigned upload route allows for one browser upload; returned by `getSignedToken`. */
+export interface PresignedUploadAuthorization {
+  /** Token to sign the upload URL with, usually cached by the route. */
+  readonly token: SigningToken;
+
+  /** Constraints signed into the URL; they may only narrow the token's. */
+  readonly urlOptions?:
+    | (Omit<
+        Extract<PresignOptions, { readonly operation: "put" }>,
+        "operation" | "pathname" | "onUploadCompleted"
+      > & {
+        /** As {@link UploadAuthorization.callbackUrl}. */
+        readonly callbackUrl?: string | undefined;
+        /** Passed to `onUploadCompleted`; defaults to the browser's `clientPayload`. */
+        readonly tokenPayload?: string | undefined;
+      })
+    | undefined;
+}
+
+/** Hooks of a presigned upload route. */
+export interface PresignedUploadHandlerOptions<E, R, E2, R2> {
+  /** Authenticate and authorize the user, then choose the token and constraints. */
+  readonly getSignedToken: (
+    request: UploadRequest,
+  ) => Effect.Effect<PresignedUploadAuthorization, E, R>;
+
+  /** As {@link UploadHandlerOptions.onUploadCompleted}; callbacks are verified with Ed25519. */
+  readonly onUploadCompleted?:
+    | ((event: UploadCompleted) => Effect.Effect<void, E2, R2>)
+    | undefined;
+}
+
+/**
+ * The server side of browser uploads: a route that authorizes uploads and receives the store's
+ * upload-completed callbacks.
+ *
+ * ```ts
+ * export const POST = HttpEffect.toWebHandlerLayer(
+ *   BlobUploads.use((uploads) =>
+ *     uploads.handler({ onBeforeGenerateToken: authorize, onUploadCompleted: saveAvatar }),
+ *   ).pipe(Effect.catchTag("Unauthorized", () => HttpServerResponse.empty({ status: 401 }))),
+ *   AppLayer,
+ * ).handler;
+ * ```
+ */
+export class BlobUploads extends Context.Service<
+  BlobUploads,
+  {
+    /**
+     * Sign a client token with the store's read-write token. Defaults `validUntil` to 30 seconds
+     * from now; an `ifMatch` without `allowOverwrite` allows overwriting.
+     */
+    readonly generateClientToken: (
+      options: ClientTokenOptions,
+    ) => Effect.Effect<ClientToken, BlobReadWriteTokenRequired>;
+
+    /**
+     * Handle one request to a client-token upload route (`handleUpload`): answer
+     * `blob.generate-client-token` with `{ type, clientToken }` (valid for one hour unless
+     * `validUntil` says otherwise) and acknowledge a verified `blob.upload-completed` with
+     * `{ type, response: "ok" }`. Requires a read-write token.
+     */
+    readonly handler: <E, R, E2 = never, R2 = never>(
+      options: UploadHandlerOptions<E, R, E2, R2>,
+    ) => Effect.Effect<
+      HttpServerResponse.HttpServerResponse,
+      E | E2 | BlobUploadEventRejected | BlobReadWriteTokenRequired,
+      HttpServerRequest.HttpServerRequest | R | R2
+    >;
+
+    /**
+     * Handle one request to a presigned upload route (`handleUploadPresigned`): answer
+     * `blob.generate-presigned-url` with `{ type, presignedUrlPayload }` and acknowledge a
+     * `blob.upload-completed` verified against `BLOB_WEBHOOK_PUBLIC_KEY`. Works with OIDC.
+     */
+    readonly presignedHandler: <E, R, E2 = never, R2 = never>(
+      options: PresignedUploadHandlerOptions<E, R, E2, R2>,
+    ) => Effect.Effect<
+      HttpServerResponse.HttpServerResponse,
+      E | E2 | BlobUploadEventRejected | BlobPresignFailed,
+      HttpServerRequest.HttpServerRequest | R | R2
+    >;
+  }
+>()("@effect-vercel/blob/BlobUploads") {}