@upstash/qstash 2.6.0 → 2.6.2

package/README.md

@@ -3,7 +3,6 @@
 ![npm (scoped)](https://img.shields.io/npm/v/@upstash/qstash)
 
 > [!NOTE] > **This project is in GA Stage.**
->
 > The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes.
 > The Upstash team is committed to maintaining and improving its functionality.
 
@@ -42,7 +41,7 @@ npm install @upstash/qstash
 
 ### Get your authorization token
 
-Go to [upstash](https://console.upstash.com/qstash) and copy the token.
+Go to [Upstash Console](https://console.upstash.com/qstash) and copy the QSTASH_TOKEN.
 
 ## Basic Usage:
 
@@ -106,16 +105,14 @@ const isValid = await r.verify({
 No need for complicated setup your LLM request. We'll call LLM and schedule it for your serverless needs.
 
 ```ts
-import { Client } from "@upstash/qstash";
+import { Client, openai } from "@upstash/qstash";
 
 const c = new Client({
   token: "<QSTASH_TOKEN>",
 });
 
 const result = await client.publishJSON({
-  llmProvider: "openai", // We currently support open-ai and together-ai, but QStash will work with any OpenAI compatible API
-  llmToken: "YOUR_TOKEN",
-  url: "OPEN_AI_COMPATIBLE_BASE_URL",
+  api: { name: "llm", provider: openai({ token: process.env.OPENAI_API_KEY! }) },
   body: {
     model: "gpt-3.5-turbo",
     messages: [
@@ -131,13 +128,14 @@ const result = await client.publishJSON({
 
 ### Chatting with your favorite LLM
 
-You can easily start streaming Upstash, OpenAI or TogetherAI responses from your favorite framework(Next.js) or library
+You can easily start streaming Upstash or OpenAI responses from your favorite framework(Next.js) or library
 
 ```ts
+import { upstash } from "@upstash/qstash";
+
 const response = await client.chat().create({
-  provider: "upstash", // Optionally, provider: "openai"
+  provider: upstash(), // Optionally, provider: "custom({token: "XXX", baseUrl: "https://api.openai.com"})". This will allow you to call every OpenAI compatible API out there.
   model: "meta-llama/Meta-Llama-3-8B-Instruct", // Optionally, model: "gpt-3.5-turbo",
-  llmToken: process.env.OPENAI_API_KEY!,
   messages: [
     {
       role: "system",

package/index.d.mts

@@ -68,7 +68,10 @@ type Event = {
     error?: string;
     url: string;
     urlGroup?: string;
+    topicName?: string;
     endpointName?: string;
+    header?: Record<string, string>;
+    body?: string;
 };
 type EventPayload = Omit<Event, "urlGroup"> & {
     topicName: string;
@@ -99,6 +102,32 @@ type RateLimit = {
     reset: string | null;
 };
 
+type ProviderReturnType = {
+    owner: "upstash" | "openai" | "custom";
+    baseUrl: string;
+    token: string;
+};
+declare const upstash: () => {
+    owner: "upstash";
+    baseUrl: "https://qstash.upstash.io/llm";
+    token: string;
+};
+declare const openai: ({ token, }: {
+    token: string;
+}) => {
+    owner: "openai";
+    baseUrl: "https://api.openai.com";
+    token: string;
+};
+declare const custom: ({ baseUrl, token, }: {
+    token: string;
+    baseUrl: string;
+}) => {
+    owner: "custom";
+    baseUrl: string;
+    token: string;
+};
+
 type ChatCompletionMessage = {
     role: "system" | "assistant" | "user";
     content: string;
@@ -164,7 +193,6 @@ type StreamDisabled = {
 } | object;
 type StreamParameter = StreamEnabled | StreamDisabled;
 type OpenAIChatModel = "gpt-4-turbo" | "gpt-4-turbo-2024-04-09" | "gpt-4-0125-preview" | "gpt-4-turbo-preview" | "gpt-4-1106-preview" | "gpt-4-vision-preview" | "gpt-4" | "gpt-4-0314" | "gpt-4-0613" | "gpt-4-32k" | "gpt-4-32k-0314" | "gpt-4-32k-0613" | "gpt-3.5-turbo" | "gpt-3.5-turbo-16k" | "gpt-3.5-turbo-0301" | "gpt-3.5-turbo-0613" | "gpt-3.5-turbo-1106" | "gpt-3.5-turbo-0125" | "gpt-3.5-turbo-16k-0613";
-type TogetherAIChatModel = "zero-one-ai/Yi-34B-Chat" | "allenai/OLMo-7B-Instruct" | "allenai/OLMo-7B-Twin-2T" | "allenai/OLMo-7B" | "Austism/chronos-hermes-13b" | "cognitivecomputations/dolphin-2.5-mixtral-8x7b" | "databricks/dbrx-instruct" | "deepseek-ai/deepseek-coder-33b-instruct" | "deepseek-ai/deepseek-llm-67b-chat" | "garage-bAInd/Platypus2-70B-instruct" | "google/gemma-2b-it" | "google/gemma-7b-it" | "Gryphe/MythoMax-L2-13b" | "lmsys/vicuna-13b-v1.5" | "lmsys/vicuna-7b-v1.5" | "codellama/CodeLlama-13b-Instruct-hf" | "codellama/CodeLlama-34b-Instruct-hf" | "codellama/CodeLlama-70b-Instruct-hf" | "codellama/CodeLlama-7b-Instruct-hf" | "meta-llama/Llama-2-70b-chat-hf" | "meta-llama/Llama-2-13b-chat-hf" | "meta-llama/Llama-2-7b-chat-hf" | "meta-llama/Llama-3-8b-chat-hf" | "meta-llama/Llama-3-70b-chat-hf" | "mistralai/Mistral-7B-Instruct-v0.1" | "mistralai/Mistral-7B-Instruct-v0.2" | "mistralai/Mistral-7B-Instruct-v0.3" | "mistralai/Mixtral-8x7B-Instruct-v0.1" | "mistralai/Mixtral-8x22B-Instruct-v0.1" | "NousResearch/Nous-Capybara-7B-V1p9" | "NousResearch/Nous-Hermes-2-Mistral-7B-DPO" | "NousResearch/Nous-Hermes-2-Mixtral-8x7B-DPO" | "NousResearch/Nous-Hermes-2-Mixtral-8x7B-SFT" | "NousResearch/Nous-Hermes-llama-2-7b" | "NousResearch/Nous-Hermes-Llama2-13b" | "NousResearch/Nous-Hermes-2-Yi-34B" | "openchat/openchat-3.5-1210" | "Open-Orca/Mistral-7B-OpenOrca" | "Qwen/Qwen1.5-0.5B-Chat" | "Qwen/Qwen1.5-1.8B-Chat" | "Qwen/Qwen1.5-4B-Chat" | "Qwen/Qwen1.5-7B-Chat" | "Qwen/Qwen1.5-14B-Chat" | "Qwen/Qwen1.5-32B-Chat" | "Qwen/Qwen1.5-72B-Chat" | "Qwen/Qwen1.5-110B-Chat" | "Qwen/Qwen2-72B-Instruct" | "snorkelai/Snorkel-Mistral-PairRM-DPO" | "Snowflake/snowflake-arctic-instruct" | "togethercomputer/alpaca-7b" | "teknium/OpenHermes-2-Mistral-7B" | "teknium/OpenHermes-2p5-Mistral-7B" | "togethercomputer/Llama-2-7B-32K-Instruct" | "togethercomputer/RedPajama-INCITE-Chat-3B-v1" | "togethercomputer/RedPajama-INCITE-7B-Chat" | "togethercomputer/StripedHyena-Nous-7B" | "Undi95/ReMM-SLERP-L2-13B" | "Undi95/Toppy-M-7B" | "WizardLM/WizardLM-13B-V1.2" | "upstage/SOLAR-10.7B-Instruct-v1.0";
 type ChatRequestCommonFields = {
     frequency_penalty?: number;
     logit_bias?: Record<string, number>;
@@ -186,18 +214,14 @@ type PromptChatRequestFields = ChatRequestCommonFields & {
 type ChatRequestFields = ChatRequestCommonFields & {
     messages: ChatCompletionMessage[];
 };
-type LlmProvider = "openai" | "togetherai";
-type LlmProviderBaseUrl = "https://api.openai.com" | "https://api.together.xyz";
 type ChatRequestProviders = {
-    provider: "openai";
+    provider: ProviderReturnType;
     model: OpenAIChatModel;
-    llmToken: string;
 } | {
-    provider: "togetherai";
-    model: TogetherAIChatModel;
-    llmToken: string;
+    provider: ProviderReturnType;
+    model: string;
 } | {
-    provider: "upstash";
+    provider: ProviderReturnType;
     model: ChatModel;
 };
 type PromptChatRequest<TStream extends StreamParameter> = ChatRequestProviders & PromptChatRequestFields & TStream;
@@ -268,10 +292,23 @@ type Message = {
      * The url group name if this message was sent to a urlGroup.
      */
     urlGroup?: string;
+    /**
+     * Deprecated. The topic name if this message was sent to a urlGroup. Use urlGroup instead
+     */
+    topicName?: string;
     /**
      * The url where this message is sent to.
      */
     url: string;
+    /**
+     * The endpoint name of the message if the endpoint is given a
+     * name within the url group.
+     */
+    endpointName?: string;
+    /**
+     * The api name if this message was sent to an api
+     */
+    api?: string;
     /**
      * The http method used to deliver the message
      */
@@ -284,6 +321,11 @@ type Message = {
      * The http body sent to your API
      */
     body?: string;
+    /**
+     * The base64 encoded body if the body contains non-UTF-8 characters,
+     * `None` otherwise.
+     */
+    bodyBase64?: string;
     /**
      * Maxmimum number of retries.
      */
@@ -308,6 +350,14 @@ type Message = {
      * The queue name if this message was sent to a queue.
      */
     queueName?: string;
+    /**
+     * The scheduleId of the message if the message is triggered by a schedule
+     */
+    scheduleId?: string;
+    /**
+     * IP address of the publisher of this message
+     */
+    callerIp?: string;
 };
 type MessagePayload = Omit<Message, "urlGroup"> & {
     topicName: string;
@@ -323,10 +373,75 @@ declare class Messages {
      * Cancel a message
      */
     delete(messageId: string): Promise<void>;
+    deleteMany(messageIds: string[]): Promise<number>;
+    deleteAll(): Promise<number>;
 }
 
 type DlqMessage = Message & {
+    /**
+     * The unique id within the DLQ
+     */
     dlqId: string;
+    /**
+     * The HTTP status code of the last failed delivery attempt
+     */
+    responseStatus?: number;
+    /**
+     * The response headers of the last failed delivery attempt
+     */
+    responseHeader?: Record<string, string[]>;
+    /**
+     * The response body of the last failed delivery attempt if it is
+     * composed of UTF-8 characters only, `None` otherwise.
+     */
+    responseBody?: string;
+    /**
+     * The base64 encoded response body of the last failed delivery attempt
+     * if the response body contains non-UTF-8 characters, `None` otherwise.
+     */
+    responseBodyBase64?: string;
+};
+type DLQFilter = {
+    /**
+     * Filter DLQ entries by message id
+     */
+    messageId?: string;
+    /**
+     * Filter DLQ entries by url
+     */
+    url?: string;
+    /**
+     * Filter DLQ entries by url group name
+     */
+    urlGroup?: string;
+    /**
+     * Filter DLQ entries by api name
+     */
+    api?: string;
+    /**
+     * Filter DLQ entries by queue name
+     */
+    queueName?: string;
+    /**
+     * Filter DLQ entries by schedule id
+     */
+    scheduleId?: string;
+    /**
+     * Filter DLQ entries by starting time, in milliseconds
+     */
+    fromDate?: number;
+    /**
+     * Filter DLQ entries by ending time, in milliseconds
+     */
+    toDate?: number;
+    /**
+     * Filter DLQ entries by HTTP status of the response
+     */
+    responseStatus?: number;
+    /**
+     * Filter DLQ entries by IP address of the publisher of the message
+     */
+    callerIp?: string;
 };
 declare class DLQ {
     private readonly http;
@@ -336,6 +451,8 @@ declare class DLQ {
      */
     listMessages(options?: {
         cursor?: string;
+        count?: number;
+        filter?: DLQFilter;
     }): Promise<{
         messages: DlqMessage[];
         cursor?: string;
@@ -354,6 +471,45 @@ declare class DLQ {
     }>;
 }
 
+declare class Chat {
+    private http;
+    private token;
+    constructor(http: Requester, token: string);
+    private static toChatRequest;
+    /**
+     * Calls the Upstash completions api given a ChatRequest.
+     *
+     * Returns a ChatCompletion or a stream of ChatCompletionChunks
+     * if stream is enabled.
+     *
+     * @param request ChatRequest with messages
+     * @returns Chat completion or stream
+     */
+    create: <TStream extends StreamParameter>(request: ChatRequest<TStream>) => Promise<TStream extends StreamEnabled ? AsyncIterable<ChatCompletionChunk> : ChatCompletion>;
+    /**
+     * Calls the Upstash completions api given a ChatRequest.
+     *
+     * Returns a ChatCompletion or a stream of ChatCompletionChunks
+     * if stream is enabled.
+     *
+     * @param request ChatRequest with messages
+     * @returns Chat completion or stream
+     */
+    private createThirdParty;
+    /**
+     * Calls the Upstash completions api given a PromptRequest.
+     *
+     * Returns a ChatCompletion or a stream of ChatCompletionChunks
+     * if stream is enabled.
+     *
+     * @param request PromptRequest with system and user messages.
+     *    Note that system parameter shouldn't be passed in the case of
+     *    mistralai/Mistral-7B-Instruct-v0.2 model.
+     * @returns Chat completion or stream
+     */
+    prompt: <TStream extends StreamParameter>(request: PromptChatRequest<TStream>) => Promise<TStream extends StreamEnabled ? AsyncIterable<ChatCompletionChunk> : ChatCompletion>;
+}
+
 type QueueResponse = {
     createdAt: number;
     updatedAt: number;
@@ -426,10 +582,12 @@ type Schedule = {
     method: string;
     header?: Record<string, string[]>;
     body?: string;
+    bodyBase64?: string;
     retries: number;
     delay?: number;
     callback?: string;
     failureCallback?: string;
+    callerIp?: string;
     isPaused: true | undefined;
 };
 type CreateScheduleRequest = {
@@ -621,44 +779,6 @@ declare class UrlGroups {
     delete(name: string): Promise<void>;
 }
 
-declare class Chat {
-    private http;
-    constructor(http: Requester);
-    private static toChatRequest;
-    /**
-     * Calls the Upstash completions api given a ChatRequest.
-     *
-     * Returns a ChatCompletion or a stream of ChatCompletionChunks
-     * if stream is enabled.
-     *
-     * @param request ChatRequest with messages
-     * @returns Chat completion or stream
-     */
-    create: <TStream extends StreamParameter>(request: ChatRequest<TStream>) => Promise<TStream extends StreamEnabled ? AsyncIterable<ChatCompletionChunk> : ChatCompletion>;
-    /**
-     * Calls the Upstash completions api given a ChatRequest.
-     *
-     * Returns a ChatCompletion or a stream of ChatCompletionChunks
-     * if stream is enabled.
-     *
-     * @param request ChatRequest with messages
-     * @returns Chat completion or stream
-     */
-    private createThirdParty;
-    /**
-     * Calls the Upstash completions api given a PromptRequest.
-     *
-     * Returns a ChatCompletion or a stream of ChatCompletionChunks
-     * if stream is enabled.
-     *
-     * @param request PromptRequest with system and user messages.
-     *    Note that system parameter shouldn't be passed in the case of
-     *    mistralai/Mistral-7B-Instruct-v0.2 model.
-     * @returns Chat completion or stream
-     */
-    prompt: <TStream extends StreamParameter>(request: PromptChatRequest<TStream>) => Promise<TStream extends StreamEnabled ? AsyncIterable<ChatCompletionChunk> : ChatCompletion>;
-}
-
 type ClientConfig = {
     /**
      * Url of the qstash api server.
@@ -793,7 +913,7 @@ type PublishRequest<TBody = BodyInit> = {
     url: string;
     urlGroup?: never;
     api?: never;
-    llmProvider?: never;
+    topic?: never;
 } | {
     url?: never;
     /**
@@ -801,30 +921,26 @@ type PublishRequest<TBody = BodyInit> = {
      */
     urlGroup: string;
     api?: never;
-    llmProvider?: never;
+    topic?: never;
 } | {
-    url?: never;
+    url?: string;
     urlGroup?: never;
     /**
      * The api endpoint the request should be sent to.
      */
-    api: "llm";
-    llmProvider?: never;
+    api: {
+        name: "llm";
+        provider?: ProviderReturnType;
+    };
+    topic?: never;
 } | {
-    /**
-     * 3rd party provider url such as OpenAI: https://api.openai.com/v1/chat/completions
-     */
-    url?: string;
+    url?: never;
     urlGroup?: never;
-    api?: never;
-    /**
-     * 3rd party provider name such as OpenAI, TogetherAI
-     */
-    llmProvider: LlmProvider;
+    api: never;
     /**
-     * 3rd party provider secret key
+     * Deprecated. The topic the message should be sent to. Same as urlGroup
      */
-    llmToken?: string;
+    topic?: string;
 });
 type PublishJsonRequest = Omit<PublishRequest, "body"> & {
     /**
@@ -842,6 +958,8 @@ type EventsRequestFilter = {
     state?: State;
     url?: string;
     urlGroup?: string;
+    topicName?: string;
+    api?: string;
     scheduleId?: string;
     queueName?: string;
     fromDate?: number;
@@ -857,6 +975,7 @@ type QueueRequest = {
 };
 declare class Client {
     http: Requester;
+    private token;
     constructor(config: ClientConfig);
     /**
      * Access the urlGroup API.
@@ -864,6 +983,14 @@ declare class Client {
      * Create, read, update or delete urlGroups.
      */
     get urlGroups(): UrlGroups;
+    /**
+     * Deprecated. Use urlGroups instead.
+     *
+     * Access the topic API.
+     *
+     * Create, read, update or delete topics.
+     */
+    get topics(): UrlGroups;
     /**
      * Access the dlq API.
      *
@@ -950,10 +1077,25 @@ declare class QstashError extends Error {
     constructor(message: string);
 }
 declare class QstashRatelimitError extends QstashError {
+    limit: string | null;
+    remaining: string | null;
+    reset: string | null;
     constructor(args: RateLimit);
 }
 declare class QstashChatRatelimitError extends QstashError {
+    limitRequests: string | null;
+    limitTokens: string | null;
+    remainingRequests: string | null;
+    remainingTokens: string | null;
+    resetRequests: string | null;
+    resetTokens: string | null;
     constructor(args: ChatRateLimit);
 }
+declare class QstashDailyRatelimitError extends QstashError {
+    limit: string | null;
+    remaining: string | null;
+    reset: string | null;
+    constructor(args: RateLimit);
+}
 
-export { type AddEndpointsRequest, type BodyInit, Chat, type ChatCompletion, type ChatCompletionChunk, type ChatCompletionMessage, type ChatRateLimit, type ChatRequest, Client, type CreateScheduleRequest, type Endpoint, type Event, type EventPayload, type EventsRequest, type GetEventsPayload, type GetEventsResponse, type HeadersInit, type LlmProvider, type LlmProviderBaseUrl, type Message, type MessagePayload, Messages, type OpenAIChatModel, type PromptChatRequest, type PublishBatchRequest, type PublishJsonRequest, type PublishRequest, type PublishResponse, type PublishToApiResponse, type PublishToUrlGroupsResponse, type PublishToUrlResponse, QstashChatRatelimitError, QstashError, QstashRatelimitError, type QueueRequest, type RateLimit, Receiver, type ReceiverConfig, type RemoveEndpointsRequest, type RequestOptions, type Schedule, Schedules, SignatureError, type State, type StreamDisabled, type StreamEnabled, type StreamParameter, type TogetherAIChatModel, type UrlGroup, UrlGroups, type VerifyRequest, type WithCursor };
+export { type AddEndpointsRequest, type BodyInit, Chat, type ChatCompletion, type ChatCompletionChunk, type ChatCompletionMessage, type ChatRateLimit, type ChatRequest, Client, type CreateScheduleRequest, type Endpoint, type Event, type EventPayload, type EventsRequest, type GetEventsPayload, type GetEventsResponse, type HeadersInit, type Message, type MessagePayload, Messages, type OpenAIChatModel, type PromptChatRequest, type ProviderReturnType, type PublishBatchRequest, type PublishJsonRequest, type PublishRequest, type PublishResponse, type PublishToApiResponse, type PublishToUrlGroupsResponse, type PublishToUrlResponse, QstashChatRatelimitError, QstashDailyRatelimitError, QstashError, QstashRatelimitError, type QueueRequest, type RateLimit, Receiver, type ReceiverConfig, type RemoveEndpointsRequest, type RequestOptions, type Schedule, Schedules, SignatureError, type State, type StreamDisabled, type StreamEnabled, type StreamParameter, type UrlGroup, UrlGroups, type VerifyRequest, type WithCursor, custom, openai, upstash };