@upstash/qstash 2.9.1-rc.1 → 2.10.0

package/{client-Gv4WRTxB.d.ts → client-CsM1dTnz.d.mts}

@@ -505,32 +505,16 @@ type RetryConfig = false | {
     backoff?: (retryCount: number) => number;
 };
 
-type NeverAll<T> = {
-    [K in keyof T]?: never;
-};
 type RequireAtLeastOne<T> = {
     [K in keyof T]-?: Required<Pick<T, K>>;
 }[keyof T];
-/**
- * Three-way exclusive union: at-least-one-filter OR `{ all: true }` OR IDs.
- * Exactly one branch can be satisfied at a time.
- *
- * The filter and all branches intentionally omit `NeverAll<Ids>` so that
- * TypeScript's `"key" in request` narrowing correctly isolates the IDs branch.
- * Excess-property checks on object literals still prevent mixing ID keys with filters.
- */
-type FilterAllOrIds<F extends Record<string, unknown>, Ids extends Record<string, unknown>> = (F & RequireAtLeastOne<F> & {
-    all?: never;
-}) | ({
-    all: true;
-} & NeverAll<F>) | (Ids & NeverAll<F> & {
-    all?: never;
-});
+type NeverKeys<T> = {
+    [K in keyof T]?: never;
+};
+/** Two-branch exclusive union: A or B, never both. */
+type Exclusive<A, B> = (A & NeverKeys<B>) | (B & NeverKeys<A>);
 /** Shared filter fields accepted by every qstash & workflow endpoint. */
 type UniversalFilterFields = {
-    /**
-     * aslkdjasd
-     */
     fromDate?: Date | number;
     toDate?: Date | number;
     callerIp?: string;
@@ -552,19 +536,100 @@ type DLQResponseFields = {
 /** Logs-specific filter fields exclusive to log endpoints. */
 type LogsFilterFields = {
     state?: State;
-    messageIds?: string[];
 };
+type DLQFilterFields = UniversalFilterFields & QStashIdentityFields & DLQResponseFields & {
+    /**
+     * @deprecated `api` filter has been removed from the API and will be ignored
+     */
+    api?: string;
+};
+type MessageCancelFilterFields = UniversalFilterFields & Omit<QStashIdentityFields, "messageId">;
 /**
- * Doesn't allow a single messageId because this is a bulk action
+ * Doesn't allow a single messageId because this is a bulk action.
+ * Cancel does not support cursor.
  */
-type MessageCancelFilters = FilterAllOrIds<UniversalFilterFields & Omit<QStashIdentityFields, "messageId">, {
+type MessageCancelFilters = {
     messageIds: string[];
-}>;
-type DLQBulkActionFilters = FilterAllOrIds<UniversalFilterFields & QStashIdentityFields & DLQResponseFields, {
+    filter?: never;
+    all?: never;
+    count?: never;
+} | ({
+    filter: RequireAtLeastOne<MessageCancelFilterFields>;
+    messageIds?: never;
+    all?: never;
+} & MessageCancelCount) | ({
+    all: true;
+    messageIds?: never;
+    filter?: never;
+} & MessageCancelCount);
+type MessageCancelCount = {
+    /**
+     * Maximum number of messages to cancel per call.
+     *
+     * @default 100
+     */
+    count?: number;
+};
+/**
+ * DLQ bulk actions support three modes:
+ * - By dlqIds (no cursor)
+ * - By filter fields (with optional cursor)
+ * - All (with optional cursor)
+ */
+type DLQBulkActionFilters = {
     dlqIds: string | string[];
+    filter?: never;
+    all?: never;
+    count?: never;
+    cursor?: never;
+} | ({
+    filter: RequireAtLeastOne<DLQFilterFields>;
+    dlqIds?: never;
+    all?: never;
+} & DLQBulkActionCount) | ({
+    all: true;
+    dlqIds?: never;
+    filter?: never;
+} & DLQBulkActionCount);
+type DLQBulkActionCount = {
+    cursor?: string;
+    /**
+     * Maximum number of messages to process per call.
+     *
+     * @default 100
+     */
+    count?: number;
+};
+type DLQListRequest = Exclusive<{
+    dlqIds: string | string[];
+}, {
+    filter?: DLQFilterFields;
+    cursor?: string;
 }>;
-type DLQListFilters = UniversalFilterFields & QStashIdentityFields & DLQResponseFields;
-type LogsListFilters = UniversalFilterFields & QStashIdentityFields & LogsFilterFields & {
+type LogsListRequest = Exclusive<{
+    messageIds: string[];
+}, {
+    filter?: LogsListFilters;
+    /**
+     * Passing `number` may silently break due to JavaScript integer precision
+     * limits — cursor values can exceed `Number.MAX_SAFE_INTEGER`. Use `string` instead.
+     */
+    cursor?: string | number;
+}>;
+type LogsListFilters = UniversalFilterFields & Omit<QStashIdentityFields, "messageId"> & LogsFilterFields & {
+    /**
+     * @deprecated `api` filter has been removed from the API and will be ignored
+     */
+    api?: string;
+    /**
+     * @deprecated use `messageIds` in the root instead of `messageId` in the `filter` object
+     *
+     * Example:
+     * ```ts
+     * await client.logs({ messageIds: ["id1", "id2"] })
+     * ```
+     */
+    messageId?: string;
     /**
      * @deprecated use `urlGroup` instead
      */
@@ -707,8 +772,19 @@ declare class Messages {
      * Can be called with:
      * - A single messageId: `cancel("id")`
      * - An array of messageIds: `cancel(["id1", "id2"])`
-     * - A filter object: `cancel({ flowControlKey: "key", label: "label" })`
+     * - A filter object: `cancel({ filter: { flowControlKey: "key", label: "label" } })`
      * - All messages: `cancel({ all: true })`
+     *
+     * Pass `count` to limit the number of messages processed per call (defaults to 100).
+     * Call in a loop until `cancelled` is 0:
+     *
+     * ```ts
+     * let cancelled: number;
+     * do {
+     *   const result = await messages.cancel({ all: true, count: 100 });
+     *   cancelled = result.cancelled;
+     * } while (cancelled > 0);
+     * ```
      */
     cancel(request: string | string[] | MessageCancelFilters): Promise<{
         cancelled: number;
@@ -761,15 +837,15 @@ declare class DLQ {
     constructor(http: Requester);
     /**
      * List messages in the dlq
+     *
+     * Can be called with:
+     * - Filters: `listMessages({ filter: { url: "https://example.com" } })`
+     * - DLQ IDs: `listMessages({ dlqIds: ["id1", "id2"] })`
+     * - No filter (list all): `listMessages()`
      */
     listMessages(options?: {
-        cursor?: string;
         count?: number;
-        /** Defaults to `latestFirst` */
-        order?: "earliestFirst" | "latestFirst";
-        trimBody?: number;
-        filter?: DLQListFilters;
-    }): Promise<{
+    } & DLQListRequest): Promise<{
         messages: DlqMessage[];
         cursor?: string;
     }>;
@@ -780,10 +856,19 @@ declare class DLQ {
      * - A single dlqId: `delete("id")`
      * - An array of dlqIds: `delete(["id1", "id2"])`
      * - An object with dlqIds: `delete({ dlqIds: ["id1", "id2"] })`
-     * - A filter object: `delete({ url: "https://example.com", label: "label" })`
+     * - A filter object: `delete({ filter: { url: "https://example.com", label: "label" } })`
      * - All messages: `delete({ all: true })`
      *
-     * Note: passing an empty array returns `{ deleted: 0 }` without making a request.
+     * Pass `count` to limit the number of messages processed per call (defaults to 100).
+     * Call in a loop until cursor is undefined:
+     *
+     * ```ts
+     * let cursor: string | undefined;
+     * do {
+     *   const result = await dlq.delete({ all: true, count: 100, cursor });
+     *   cursor = result.cursor;
+     * } while (cursor);
+     * ```
      */
     delete(request: string | string[] | DLQBulkActionFilters): Promise<{
         deleted: number;
@@ -807,10 +892,19 @@ declare class DLQ {
      * - A single dlqId: `retry("id")`
      * - An array of dlqIds: `retry(["id1", "id2"])`
      * - An object with dlqIds: `retry({ dlqIds: ["id1", "id2"] })`
-     * - A filter object: `retry({ url: "https://example.com", label: "label" })`
+     * - A filter object: `retry({ filter: { url: "https://example.com", label: "label" } })`
      * - All messages: `retry({ all: true })`
      *
-     * Note: passing an empty array returns `{ responses: [] }` without making a request.
+     * Pass `count` to limit the number of messages processed per call (defaults to 100).
+     * Call in a loop until cursor is undefined:
+     *
+     * ```ts
+     * let cursor: string | undefined;
+     * do {
+     *   const result = await dlq.retry({ all: true, count: 100, cursor });
+     *   cursor = result.cursor;
+     * } while (cursor);
+     * ```
      */
     retry(request: string | string[] | DLQBulkActionFilters): Promise<{
         cursor?: string;
@@ -820,6 +914,131 @@ declare class DLQ {
     }>;
 }
 
+type FlowControlInfo = {
+    /**
+     * The flow control key.
+     */
+    flowControlKey: string;
+    /**
+     * The number of messages waiting in the wait list.
+     */
+    waitListSize: number;
+    /**
+     * The maximum parallelism configured for this flow control key.
+     */
+    parallelismMax: number;
+    /**
+     * The current number of active requests for this flow control key.
+     */
+    parallelismCount: number;
+    /**
+     * The maximum rate configured for this flow control key.
+     */
+    rateMax: number;
+    /**
+     * The current number of requests consumed in the current period.
+     */
+    rateCount: number;
+    /**
+     * The rate period in seconds.
+     */
+    ratePeriod: number;
+    /**
+     * The start time of the current rate period as a unix timestamp.
+     */
+    ratePeriodStart: number;
+    /**
+     * Whether message delivery is paused for this flow control key.
+     */
+    isPaused: boolean;
+    /**
+     * Whether the parallelism configuration is pinned.
+     */
+    isPinnedParallelism: boolean;
+    /**
+     * Whether the rate configuration is pinned.
+     */
+    isPinnedRate: boolean;
+};
+type GlobalParallelismInfo = {
+    /**
+     * The maximum global parallelism.
+     */
+    parallelismMax: number;
+    /**
+     * The current number of active requests globally.
+     */
+    parallelismCount: number;
+};
+type PinFlowControlOptions = {
+    /**
+     * The parallelism value to apply to the flow-control key.
+     */
+    parallelism?: number;
+    /**
+     * The rate value to apply to the flow-control key.
+     */
+    rate?: number;
+    /**
+     * The period value to apply to the flow-control key, in seconds.
+     */
+    period?: number;
+};
+type UnpinFlowControlOptions = {
+    /**
+     * Whether to unpin the parallelism configuration.
+     */
+    parallelism?: boolean;
+    /**
+     * Whether to unpin the rate configuration.
+     */
+    rate?: boolean;
+};
+declare class FlowControlApi {
+    private readonly http;
+    constructor(http: Requester);
+    /**
+     * Get a single flow control by key.
+     */
+    get(flowControlKey: string): Promise<FlowControlInfo>;
+    /**
+     * Get the global parallelism info.
+     */
+    getGlobalParallelism(): Promise<GlobalParallelismInfo>;
+    /**
+     * Pause message delivery for a flow-control key.
+     *
+     * Messages already in the waitlist will remain there.
+     * New incoming messages will be added directly to the waitlist.
+     */
+    pause(flowControlKey: string): Promise<void>;
+    /**
+     * Resume message delivery for a flow-control key.
+     */
+    resume(flowControlKey: string): Promise<void>;
+    /**
+     * Pin a processing configuration for a flow-control key.
+     *
+     * While pinned, the system ignores configurations provided by incoming
+     * messages and uses the pinned configuration instead.
+     */
+    pin(flowControlKey: string, options: PinFlowControlOptions): Promise<void>;
+    /**
+     * Remove the pinned configuration for a flow-control key.
+     *
+     * After unpinning, the system resumes updating the configuration
+     * based on incoming messages.
+     */
+    unpin(flowControlKey: string, options: UnpinFlowControlOptions): Promise<void>;
+    /**
+     * Reset the rate configuration state for a flow-control key.
+     *
+     * Clears the current rate count and immediately ends the current period.
+     * The current timestamp becomes the start of the new rate period.
+     */
+    resetRate(flowControlKey: string): Promise<void>;
+}
+
 declare class Chat {
     private http;
     private token;
@@ -1080,6 +1299,19 @@ type CreateScheduleRequest = {
      * @default undefined
      */
     label?: string;
+    /**
+     * Configure which fields should be redacted in logs.
+     *
+     * - `body: true` redacts the request body
+     * - `header: true` redacts all headers
+     * - `header: ["X"]` redacts specific headers (e.g., ["Authorization"])
+     *
+     * @default undefined
+     */
+    redact?: {
+        body?: true;
+        header?: true | string[];
+    };
 } & Pick<PublishRequest, "retryDelay">;
 declare class Schedules {
     private readonly http;
@@ -2037,6 +2269,19 @@ type PublishRequest<TBody = BodyInit> = {
      * @default undefined
      */
     label?: string;
+    /**
+     * Configure which fields should be redacted in logs.
+     *
+     * - `body: true` redacts the request body
+     * - `header: true` redacts all headers
+     * - `header: ["X"]` redacts specific headers (e.g., ["Authorization"])
+     *
+     * @default undefined
+     */
+    redact?: {
+        body?: true;
+        header?: true | string[];
+    };
 } & ({
     /**
      * The url where the message should be sent to.
@@ -2121,14 +2366,9 @@ type PublishJsonRequest = Omit<PublishRequest, "body"> & {
     body: unknown;
 };
 type LogsRequest = {
-    cursor?: string | number;
     /** Max 1000. Defaults to 10 when `groupBy` is used. */
     count?: number;
-    /** Defaults to `latestFirst` */
-    order?: "earliestFirst" | "latestFirst";
-    trimBody?: number;
-    filter?: LogsListFilters;
-};
+} & LogsListRequest;
 /**
  * Deprecated. Use `LogsRequest` instead.
  *
@@ -2190,6 +2430,12 @@ declare class Client {
      * Create, read or delete schedules.
      */
     get schedules(): Schedules;
+    /**
+     * Access the flow control API.
+     *
+     * List, get, or reset flow controls.
+     */
+    get flowControl(): FlowControlApi;
     /**
      * Access the workflow API.
      *
@@ -2285,4 +2531,4 @@ type PublishResponse<TRequest> = TRequest extends {
     urlGroup: string;
 } ? PublishToUrlGroupsResponse : PublishToApiResponse;
 
-export { type ChatCompletionChunk as $, type AddEndpointsRequest as A, BaseProvider as B, type ChatRateLimit as C, type LogPayload as D, type EmailOwner as E, type FailureFunctionPayload as F, type GetLogsResponse as G, type HTTPMethods as H, type EventPayload as I, type GetLogsPayload as J, type GetEventsPayload as K, type LLMOwner as L, type Message as M, type BodyInit as N, type HeadersInit as O, type ProviderInfo as P, type QueueRequest as Q, type RateLimit as R, type Step as S, type RequestOptions as T, type UniversalFilterFields as U, type VerifyRequest as V, type WithCursor as W, type FlowControl as X, Chat as Y, type ChatCompletionMessage as Z, type ChatCompletion as _, type ReceiverConfig as a, type StreamEnabled as a0, type StreamDisabled as a1, type StreamParameter as a2, type OpenAIChatModel as a3, type PromptChatRequest as a4, type ChatRequest as a5, upstash as a6, openai as a7, anthropic as a8, custom as a9, type RouteFunction as aa, type WorkflowServeOptions as ab, Workflow as ac, processOptions as ad, serve as ae, WorkflowContext as af, DisabledWorkflowContext as ag, type WorkflowClient as ah, type WorkflowReceiver as ai, StepTypes as aj, type StepType as ak, type RawStep as al, type SyncStepFunction as am, type AsyncStepFunction as an, type StepFunction as ao, type ParallelCallState as ap, type FinishCondition as aq, type RequiredExceptFields as ar, type LogLevel as as, type WorkflowLoggerOptions as at, WorkflowLogger as au, SignatureError as b, Receiver as c, type PublishBatchRequest as d, type PublishRequest as e, type PublishJsonRequest as f, type LogsRequest as g, type EventsRequest as h, type GetEventsResponse as i, Client as j, type PublishToApiResponse as k, type PublishToUrlResponse as l, type PublishToUrlGroupsResponse as m, type PublishResponse as n, type MessagePayload as o, Messages as p, type Schedule as q, type CreateScheduleRequest as r, Schedules as s, type Endpoint as t, type RemoveEndpointsRequest as u, type UrlGroup as v, UrlGroups as w, type State as x, type Log as y, type Event as z };
+export { type FlowControl as $, type AddEndpointsRequest as A, BaseProvider as B, type ChatRateLimit as C, UrlGroups as D, type EmailOwner as E, type FailureFunctionPayload as F, type GetLogsResponse as G, type State as H, type HTTPMethods as I, type Log as J, type Event as K, type LLMOwner as L, type Message as M, type LogPayload as N, type EventPayload as O, type ProviderInfo as P, type QueueRequest as Q, type RateLimit as R, type Step as S, type GetLogsPayload as T, type UnpinFlowControlOptions as U, type VerifyRequest as V, type GetEventsPayload as W, type WithCursor as X, type BodyInit as Y, type HeadersInit as Z, type RequestOptions as _, type ReceiverConfig as a, Chat as a0, type ChatCompletionMessage as a1, type ChatCompletion as a2, type ChatCompletionChunk as a3, type StreamEnabled as a4, type StreamDisabled as a5, type StreamParameter as a6, type OpenAIChatModel as a7, type PromptChatRequest as a8, type ChatRequest as a9, upstash as aa, openai as ab, anthropic as ac, custom as ad, type RouteFunction as ae, type WorkflowServeOptions as af, Workflow as ag, processOptions as ah, serve as ai, WorkflowContext as aj, DisabledWorkflowContext as ak, type WorkflowClient as al, type WorkflowReceiver as am, StepTypes as an, type StepType as ao, type RawStep as ap, type SyncStepFunction as aq, type AsyncStepFunction as ar, type StepFunction as as, type ParallelCallState as at, type FinishCondition as au, type RequiredExceptFields as av, type LogLevel as aw, type WorkflowLoggerOptions as ax, WorkflowLogger as ay, SignatureError as b, Receiver as c, type PublishBatchRequest as d, type PublishRequest as e, type PublishJsonRequest as f, type LogsRequest as g, type EventsRequest as h, type GetEventsResponse as i, Client as j, type PublishToApiResponse as k, type PublishToUrlResponse as l, type PublishToUrlGroupsResponse as m, type PublishResponse as n, type FlowControlInfo as o, type GlobalParallelismInfo as p, type PinFlowControlOptions as q, FlowControlApi as r, type MessagePayload as s, Messages as t, type Schedule as u, type CreateScheduleRequest as v, Schedules as w, type Endpoint as x, type RemoveEndpointsRequest as y, type UrlGroup as z };