@upstash/qstash 2.7.21 → 2.7.23

package/README.md

@@ -131,6 +131,25 @@ const result = await client.publishJSON({
 
 See [the documentation](https://docs.upstash.com/qstash) for details.
 
+## Telemetry
+
+This sdk sends anonymous telemetry headers to help us improve your experience.
+We collect the following:
+
+- SDK version
+- Platform (Cloudflare, AWS or Vercel)
+- Runtime version (node@18.x)
+
+You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable
+to any truthy value. Or setting `enableTelemetry: false` in the client options.
+
+```ts
+const client = new Client({
+  token: "<QSTASH_TOKEN>",
+  enableTelemetry: false,
+});
+```
+
 ## Contributing
 
 ### Setup

package/{chunk-QHCEWG63.mjs → chunk-G7CVCBTL.mjs}

@@ -85,7 +85,8 @@ var DLQ = class {
       messages: messagesPayload.messages.map((message) => {
         return {
           ...message,
-          urlGroup: message.topicName
+          urlGroup: message.topicName,
+          ratePerSecond: "rate" in message ? message.rate : void 0
         };
       }),
       cursor: messagesPayload.cursor
@@ -202,6 +203,7 @@ var HttpClient = class {
   options;
   retry;
   headers;
+  telemetryHeaders;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.authorization = config.authorization;
@@ -214,6 +216,7 @@ var HttpClient = class {
       backoff: config.retry?.backoff ?? ((retryCount) => Math.exp(retryCount) * 50)
     };
     this.headers = config.headers;
+    this.telemetryHeaders = config.telemetryHeaders;
   }
   async request(request) {
     const { response } = await this.requestWithBackoff(request);
@@ -515,7 +518,8 @@ var Messages = class {
     });
     const message = {
       ...messagePayload,
-      urlGroup: messagePayload.topicName
+      urlGroup: messagePayload.topicName,
+      ratePerSecond: "rate" in messagePayload ? messagePayload.rate : void 0
     };
     return message;
   }
@@ -727,7 +731,7 @@ function prefixHeaders(headers) {
   }
   return headers;
 }
-function wrapWithGlobalHeaders(headers, globalHeaders) {
+function wrapWithGlobalHeaders(headers, globalHeaders, telemetryHeaders) {
   if (!globalHeaders) {
     return headers;
   }
@@ -735,6 +739,11 @@ function wrapWithGlobalHeaders(headers, globalHeaders) {
   headers.forEach((value, key) => {
     finalHeaders.set(key, value);
   });
+  telemetryHeaders?.forEach((value, key) => {
+    if (!value)
+      return;
+    finalHeaders.append(key, value);
+  });
   return finalHeaders;
 }
 function processHeaders(request) {
@@ -772,6 +781,19 @@ function processHeaders(request) {
       headers.set("Upstash-Timeout", `${request.timeout}s`);
     }
   }
+  if (request.flowControl?.key) {
+    const parallelism = request.flowControl.parallelism?.toString();
+    const rate = request.flowControl.ratePerSecond?.toString();
+    const controlValue = [
+      parallelism ? `parallelism=${parallelism}` : void 0,
+      rate ? `rate=${rate}` : void 0
+    ].filter(Boolean);
+    if (controlValue.length === 0) {
+      throw new QstashError("Provide at least one of parallelism or ratePerSecond for flowControl");
+    }
+    headers.set("Upstash-Flow-Control-Key", request.flowControl.key);
+    headers.set("Upstash-Flow-Control-Value", controlValue.join(", "));
+  }
   return headers;
 }
 function getRequestPath(request) {
@@ -811,6 +833,15 @@ function decodeBase64(base64) {
     }
   }
 }
+function getRuntime() {
+  if (typeof process === "object" && typeof process.versions == "object" && process.versions.bun)
+    return `bun@${process.versions.bun}`;
+  if (typeof EdgeRuntime === "string")
+    return "edge-light";
+  else if (typeof process === "object" && typeof process.version === "string")
+    return `node@${process.version}`;
+  return "";
+}
 
 // src/client/queue.ts
 var Queue = class {
@@ -885,7 +916,8 @@ var Queue = class {
     }
     const headers = wrapWithGlobalHeaders(
       processHeaders(request),
-      this.http.headers
+      this.http.headers,
+      this.http.telemetryHeaders
     );
     const destination = getRequestPath(request);
     const response = await this.http.request({
@@ -988,9 +1020,24 @@ var Schedules = class {
     if (request.queueName !== void 0) {
       headers.set("Upstash-Queue-Name", request.queueName);
     }
+    if (request.flowControl?.key) {
+      const parallelism = request.flowControl.parallelism?.toString();
+      const rate = request.flowControl.ratePerSecond?.toString();
+      const controlValue = [
+        parallelism ? `parallelism=${parallelism}` : void 0,
+        rate ? `rate=${rate}` : void 0
+      ].filter(Boolean);
+      if (controlValue.length === 0) {
+        throw new QstashError(
+          "Provide at least one of parallelism or ratePerSecond for flowControl"
+        );
+      }
+      headers.set("Upstash-Flow-Control-Key", request.flowControl.key);
+      headers.set("Upstash-Flow-Control-Value", controlValue.join(", "));
+    }
     return await this.http.request({
       method: "POST",
-      headers: wrapWithGlobalHeaders(headers, this.http.headers),
+      headers: wrapWithGlobalHeaders(headers, this.http.headers, this.http.telemetryHeaders),
       path: ["v2", "schedules", request.destination],
       body: request.body
     });
@@ -999,19 +1046,27 @@ var Schedules = class {
    * Get a schedule
    */
   async get(scheduleId) {
-    return await this.http.request({
+    const schedule = await this.http.request({
       method: "GET",
       path: ["v2", "schedules", scheduleId]
     });
+    if ("rate" in schedule)
+      schedule.ratePerSecond = schedule.rate;
+    return schedule;
   }
   /**
    * List your schedules
    */
   async list() {
-    return await this.http.request({
+    const schedules = await this.http.request({
       method: "GET",
       path: ["v2", "schedules"]
     });
+    for (const schedule of schedules) {
+      if ("rate" in schedule)
+        schedule.ratePerSecond = schedule.rate;
+    }
+    return schedules;
   }
   /**
    * Delete a schedule
@@ -1108,20 +1163,37 @@ var UrlGroups = class {
   }
 };
 
+// version.ts
+var VERSION = "v2.7.23";
+
 // src/client/client.ts
 var Client = class {
   http;
   token;
   constructor(config) {
     const environment = typeof process === "undefined" ? {} : process.env;
-    const baseUrl = config?.baseUrl ? config.baseUrl.replace(/\/$/, "") : environment.QSTASH_URL ?? "https://qstash.upstash.io";
+    let baseUrl = (config?.baseUrl ?? environment.QSTASH_URL ?? "https://qstash.upstash.io").replace(/\/$/, "");
+    if (baseUrl === "https://qstash.upstash.io/v2/publish") {
+      baseUrl = "https://qstash.upstash.io";
+    }
     const token = config?.token ?? environment.QSTASH_TOKEN;
+    const enableTelemetry = environment.UPSTASH_DISABLE_TELEMETRY ? false : config?.enableTelemetry ?? true;
+    const isCloudflare = typeof caches !== "undefined" && "default" in caches;
+    const telemetryHeaders = new Headers(
+      enableTelemetry ? {
+        "Upstash-Telemetry-Sdk": `upstash-qstash-js@${VERSION}`,
+        "Upstash-Telemetry-Platform": isCloudflare ? "cloudflare" : environment.VERCEL ? "vercel" : environment.AWS_REGION ? "aws" : "",
+        "Upstash-Telemetry-Runtime": getRuntime()
+      } : {}
+    );
     this.http = new HttpClient({
       retry: config?.retry,
       baseUrl,
       authorization: `Bearer ${token}`,
       //@ts-expect-error caused by undici and bunjs type overlap
-      headers: prefixHeaders(new Headers(config?.headers ?? {}))
+      headers: prefixHeaders(new Headers(config?.headers ?? {})),
+      //@ts-expect-error caused by undici and bunjs type overlap
+      telemetryHeaders
     });
     if (!token) {
       console.warn(
@@ -1203,7 +1275,8 @@ var Client = class {
   async publish(request) {
     const headers = wrapWithGlobalHeaders(
       processHeaders(request),
-      this.http.headers
+      this.http.headers,
+      this.http.telemetryHeaders
     );
     const response = await this.http.request({
       path: ["v2", "publish", getRequestPath(request)],
@@ -1234,7 +1307,11 @@ var Client = class {
   async batch(request) {
     const messages = [];
     for (const message of request) {
-      const headers = wrapWithGlobalHeaders(processHeaders(message), this.http.headers);
+      const headers = wrapWithGlobalHeaders(
+        processHeaders(message),
+        this.http.headers,
+        this.http.telemetryHeaders
+      );
       const headerEntries = Object.fromEntries(headers.entries());
       messages.push({
         destination: getRequestPath(message),
@@ -1289,7 +1366,7 @@ var Client = class {
    * }
    * ```
    */
-  async events(request) {
+  async logs(request) {
     const query = {};
     if (typeof request?.cursor === "number" && request.cursor > 0) {
       query.cursor = request.cursor.toString();
@@ -1311,16 +1388,42 @@ var Client = class {
       method: "GET",
       query
     });
+    const logs = responsePayload.events.map((event) => {
+      return {
+        ...event,
+        urlGroup: event.topicName
+      };
+    });
     return {
       cursor: responsePayload.cursor,
-      events: responsePayload.events.map((event) => {
-        return {
-          ...event,
-          urlGroup: event.topicName
-        };
-      })
+      logs,
+      events: logs
     };
   }
+  /**
+   * @deprecated Will be removed in the next major release. Use the `logs` method instead.
+   *
+   * Retrieve your logs.
+   *
+   * The logs endpoint is paginated and returns only 100 logs at a time.
+   * If you want to receive more logs, you can use the cursor to paginate.
+   *
+   * The cursor is a unix timestamp with millisecond precision
+   *
+   * @example
+   * ```ts
+   * let cursor = Date.now()
+   * const logs: Log[] = []
+   * while (cursor > 0) {
+   *   const res = await qstash.logs({ cursor })
+   *   logs.push(...res.logs)
+   *   cursor = res.cursor ?? 0
+   * }
+   * ```
+   */
+  async events(request) {
+    return await this.logs(request);
+  }
 };
 
 // src/client/workflow/constants.ts

package/{chunk-FGKPOZOO.mjs → chunk-JZACTABH.mjs}

@@ -1,7 +1,7 @@
 import {
   Receiver,
   serve
-} from "./chunk-QHCEWG63.mjs";
+} from "./chunk-G7CVCBTL.mjs";
 
 // node_modules/defu/dist/defu.mjs
 function isPlainObject(value) {

package/{chunk-3D34OUXY.mjs → chunk-ODRYYMMA.mjs}

@@ -1,6 +1,6 @@
 import {
   BaseProvider
-} from "./chunk-QHCEWG63.mjs";
+} from "./chunk-G7CVCBTL.mjs";
 
 // src/client/api/email.ts
 var EmailProvider = class extends BaseProvider {

package/{client-DuOcoFUv.d.ts → client-CYwLcEcQ.d.mts}

@@ -64,7 +64,7 @@ declare class Receiver {
 
 type State = "CREATED" | "ACTIVE" | "DELIVERED" | "ERROR" | "RETRY" | "FAILED";
 type HTTPMethods = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-type Event = {
+type Log = {
     time: number;
     state: State;
     messageId: string;
@@ -77,13 +77,31 @@ type Event = {
     header?: Record<string, string>;
     body?: string;
 };
-type EventPayload = Omit<Event, "urlGroup"> & {
+/**
+ * Deprecated. Use the `Log` type instead.
+ *
+ * @deprecated
+ */
+type Event = Log;
+type LogPayload = Omit<Log, "urlGroup"> & {
     topicName: string;
 };
-type GetEventsPayload = {
+/**
+ * Deprecated. Use the `EventPayload` type instead.
+ *
+ * @deprecated
+ */
+type EventPayload = LogPayload;
+type GetLogsPayload = {
     cursor?: string;
-    events: EventPayload[];
+    events: LogPayload[];
 };
+/**
+ * Deprecated. use the `GetLogsPayload` type instead.
+ *
+ * @deprecated
+ */
+type GetEventsPayload = GetLogsPayload;
 type WithCursor<T> = T & {
     cursor?: number;
 };
@@ -105,6 +123,30 @@ type RateLimit = {
     remaining: string | null;
     reset: string | null;
 };
+type FlowControl = {
+    /**
+     * flow control key
+     */
+    key: string;
+} & ({
+    /**
+     * number of requests which can be active with the same flow control key
+     */
+    parallelism: number;
+    /**
+     * number of requests to activate per second with the same flow control key
+     */
+    ratePerSecond?: number;
+} | {
+    /**
+     * number of requests which can be active with the same flow control key
+     */
+    parallelism?: number;
+    /**
+     * number of requests to activate per second with the same flow control key
+     */
+    ratePerSecond: number;
+});
 
 type ProviderInfo = {
     /**
@@ -363,6 +405,7 @@ type Requester = {
     request: <TResult = unknown>(request: UpstashRequest) => Promise<UpstashResponse<TResult>>;
     requestStream: (request: UpstashRequest) => AsyncIterable<ChatCompletionChunk>;
     headers?: Headers;
+    telemetryHeaders?: Headers;
 };
 type RetryConfig = false | {
     /**
@@ -457,6 +500,18 @@ type Message = {
      * IP address of the publisher of this message
      */
     callerIp?: string;
+    /**
+     * flow control key
+     */
+    flowControlKey: string;
+    /**
+     * number of requests which can be active with the same flow control key
+     */
+    parallelism?: number;
+    /**
+     * number of requests to activate per second with the same flow control key
+     */
+    ratePerSecond?: number;
 };
 type MessagePayload = Omit<Message, "urlGroup"> & {
     topicName: string;
@@ -693,6 +748,9 @@ type Schedule = {
     callerIp?: string;
     isPaused: boolean;
     queueName?: string;
+    flowControlKey?: string;
+    parallelism?: number;
+    ratePerSecond?: number;
 };
 type CreateScheduleRequest = {
     /**
@@ -781,6 +839,11 @@ type CreateScheduleRequest = {
      * Queue name to schedule the message over.
      */
     queueName?: string;
+    /**
+     * Settings for controlling the number of active requests
+     * and number of requests per second with the same key.
+     */
+    flowControl?: FlowControl;
 };
 declare class Schedules {
     private readonly http;
@@ -1587,6 +1650,13 @@ type ClientConfig = {
      * These can be overridden by the headers in the request.
      */
     headers?: HeadersInit;
+    /**
+     * Enable telemetry to help us improve the SDK.
+     * The sdk will send the sdk version, platform and node version as telemetry headers.
+     *
+     * @default true
+     */
+    enableTelemetry?: boolean;
 };
 type PublishBatchRequest<TBody = BodyInit> = PublishRequest<TBody> & {
     queueName?: string;
@@ -1689,6 +1759,11 @@ type PublishRequest<TBody = BodyInit> = {
      * @default undefined
      */
     timeout?: Duration | number;
+    /**
+     * Settings for controlling the number of active requests
+     * and number of requests per second with the same key.
+     */
+    flowControl?: FlowControl;
 } & ({
     /**
      * The url where the message should be sent to.
@@ -1772,11 +1847,17 @@ type PublishJsonRequest = Omit<PublishRequest, "body"> & {
      */
     body: unknown;
 };
-type EventsRequest = {
+type LogsRequest = {
     cursor?: string | number;
-    filter?: EventsRequestFilter;
+    filter?: LogsRequestFilter;
 };
-type EventsRequestFilter = {
+/**
+ * Deprecated. Use `LogsRequest` instead.
+ *
+ * @deprecated
+ */
+type EventsRequest = LogsRequest;
+type LogsRequestFilter = {
     messageId?: string;
     state?: State;
     url?: string;
@@ -1789,10 +1870,22 @@ type EventsRequestFilter = {
     toDate?: number;
     count?: number;
 };
-type GetEventsResponse = {
+type GetLogsResponse = {
     cursor?: string;
-    events: Event[];
+    logs: Log[];
+    /**
+     * Deprecated. Use the `logs` field instead.
+     *
+     * @deprecated
+     */
+    events: Log[];
 };
+/**
+ * Deprecated. Use `GetLogsResponse` instead.
+ *
+ * @deprecated
+ */
+type GetEventsResponse = GetLogsResponse;
 type QueueRequest = {
     queueName?: string;
 };
@@ -1887,7 +1980,29 @@ declare class Client {
      * }
      * ```
      */
-    events(request?: EventsRequest): Promise<GetEventsResponse>;
+    logs(request?: LogsRequest): Promise<GetLogsResponse>;
+    /**
+     * @deprecated Will be removed in the next major release. Use the `logs` method instead.
+     *
+     * Retrieve your logs.
+     *
+     * The logs endpoint is paginated and returns only 100 logs at a time.
+     * If you want to receive more logs, you can use the cursor to paginate.
+     *
+     * The cursor is a unix timestamp with millisecond precision
+     *
+     * @example
+     * ```ts
+     * let cursor = Date.now()
+     * const logs: Log[] = []
+     * while (cursor > 0) {
+     *   const res = await qstash.logs({ cursor })
+     *   logs.push(...res.logs)
+     *   cursor = res.cursor ?? 0
+     * }
+     * ```
+     */
+    events(request?: LogsRequest): Promise<GetLogsResponse>;
 }
 type PublishToApiResponse = {
     messageId: string;
@@ -1903,4 +2018,4 @@ type PublishResponse<TRequest> = TRequest extends {
     urlGroup: string;
 } ? PublishToUrlGroupsResponse : PublishToApiResponse;
 
-export { upstash as $, type AddEndpointsRequest as A, BaseProvider as B, type ChatRateLimit as C, type RequestOptions as D, type EmailOwner as E, type FailureFunctionPayload as F, type GetEventsResponse as G, type HTTPMethods as H, Chat as I, type ChatCompletionMessage as J, type ChatCompletion as K, type LLMOwner as L, type Message as M, type ChatCompletionChunk as N, type StreamEnabled as O, type ProviderInfo as P, type QueueRequest as Q, type RateLimit as R, type Step as S, type StreamDisabled as T, type UrlGroup as U, type VerifyRequest as V, type WithCursor as W, type StreamParameter as X, type OpenAIChatModel as Y, type PromptChatRequest as Z, type ChatRequest as _, type ReceiverConfig as a, openai as a0, anthropic as a1, custom as a2, type RouteFunction as a3, type WorkflowServeOptions as a4, Workflow as a5, processOptions as a6, serve as a7, WorkflowContext as a8, DisabledWorkflowContext as a9, type WorkflowClient as aa, type WorkflowReceiver as ab, StepTypes as ac, type StepType as ad, type RawStep as ae, type SyncStepFunction as af, type AsyncStepFunction as ag, type StepFunction as ah, type ParallelCallState as ai, type FinishCondition as aj, type RequiredExceptFields as ak, type LogLevel as al, type WorkflowLoggerOptions as am, WorkflowLogger as an, SignatureError as b, Receiver as c, type PublishBatchRequest as d, type PublishRequest as e, type PublishJsonRequest as f, type EventsRequest as g, Client as h, type PublishToApiResponse as i, type PublishToUrlResponse as j, type PublishToUrlGroupsResponse as k, type PublishResponse as l, type MessagePayload as m, Messages as n, type Schedule as o, type CreateScheduleRequest as p, Schedules as q, type Endpoint as r, type RemoveEndpointsRequest as s, UrlGroups as t, type State as u, type Event as v, type EventPayload as w, type GetEventsPayload as x, type BodyInit as y, type HeadersInit as z };
+export { type StreamEnabled as $, type AddEndpointsRequest as A, BaseProvider as B, type ChatRateLimit as C, type EventPayload as D, type EmailOwner as E, type FailureFunctionPayload as F, type GetLogsResponse as G, type HTTPMethods as H, type GetLogsPayload as I, type GetEventsPayload as J, type BodyInit as K, type LLMOwner as L, type Message as M, type HeadersInit as N, type RequestOptions as O, type ProviderInfo as P, type QueueRequest as Q, type RateLimit as R, type Step as S, type FlowControl as T, type UrlGroup as U, type VerifyRequest as V, type WithCursor as W, Chat as X, type ChatCompletionMessage as Y, type ChatCompletion as Z, type ChatCompletionChunk as _, type ReceiverConfig as a, type StreamDisabled as a0, type StreamParameter as a1, type OpenAIChatModel as a2, type PromptChatRequest as a3, type ChatRequest as a4, upstash as a5, openai as a6, anthropic as a7, custom as a8, type RouteFunction as a9, type WorkflowServeOptions as aa, Workflow as ab, processOptions as ac, serve as ad, WorkflowContext as ae, DisabledWorkflowContext as af, type WorkflowClient as ag, type WorkflowReceiver as ah, StepTypes as ai, type StepType as aj, type RawStep as ak, type SyncStepFunction as al, type AsyncStepFunction as am, type StepFunction as an, type ParallelCallState as ao, type FinishCondition as ap, type RequiredExceptFields as aq, type LogLevel as ar, type WorkflowLoggerOptions as as, WorkflowLogger as at, 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, UrlGroups as v, type State as w, type Log as x, type Event as y, type LogPayload as z };