@upstash/qstash 2.5.5 → 2.6.0

package/README.md

@@ -2,6 +2,11 @@
 
 ![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.
+
 **QStash** is an HTTP based messaging and scheduling solution for serverless and
 edge runtimes.
 
@@ -57,7 +62,7 @@ const c = new Client({
 
 const res = await c.publishJSON({
   url: "https://my-api...",
-  // or topic: "the name or id of a topic"
+  // or urlGroup: "the name or id of a url group"
   body: {
     hello: "world",
   },
@@ -96,6 +101,58 @@ const isValid = await r.verify({
 })
 ```
 
+### Publishing a message to Open AI or any Open AI Compatible LLM
+
+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";
+
+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",
+  body: {
+    model: "gpt-3.5-turbo",
+    messages: [
+      {
+        role: "user",
+        content: "Where is the capital of Turkey?",
+      },
+    ],
+  },
+  callback: "https://oz.requestcatcher.com/",
+});
+```
+
+### Chatting with your favorite LLM
+
+You can easily start streaming Upstash, OpenAI or TogetherAI responses from your favorite framework(Next.js) or library
+
+```ts
+const response = await client.chat().create({
+  provider: "upstash", // Optionally, provider: "openai"
+  model: "meta-llama/Meta-Llama-3-8B-Instruct", // Optionally, model: "gpt-3.5-turbo",
+  llmToken: process.env.OPENAI_API_KEY!,
+  messages: [
+    {
+      role: "system",
+      content: "from now on, foo is whale",
+    },
+    {
+      role: "user",
+      content: "what exactly is foo?",
+    },
+  ],
+  stream: true,
+  temperature: 0.5,
+});
+```
+
 ## Docs
 
 See [the documentation](https://docs.upstash.com/qstash) for details.

package/index.d.mts

@@ -67,9 +67,16 @@ type Event = {
     nextDeliveryTime?: number;
     error?: string;
     url: string;
-    topicName?: string;
+    urlGroup?: string;
     endpointName?: string;
 };
+type EventPayload = Omit<Event, "urlGroup"> & {
+    topicName: string;
+};
+type GetEventsPayload = {
+    cursor?: number;
+    events: EventPayload[];
+};
 type WithCursor<T> = T & {
     cursor?: number;
 };
@@ -156,9 +163,9 @@ type StreamDisabled = {
     stream: false;
 } | object;
 type StreamParameter = StreamEnabled | StreamDisabled;
-type ChatRequest<TStream extends StreamParameter> = {
-    messages: ChatCompletionMessage[];
-    model: ChatModel;
+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>;
     logprobs?: boolean;
@@ -171,11 +178,30 @@ type ChatRequest<TStream extends StreamParameter> = {
     stop?: string | string[];
     temperature?: number;
     top_p?: number;
-} & TStream;
-type PromptRequest<TStream extends StreamParameter> = Omit<ChatRequest<TStream>, "messages" | "stream"> & {
+};
+type PromptChatRequestFields = ChatRequestCommonFields & {
     system: string;
     user: string;
-} & TStream;
+};
+type ChatRequestFields = ChatRequestCommonFields & {
+    messages: ChatCompletionMessage[];
+};
+type LlmProvider = "openai" | "togetherai";
+type LlmProviderBaseUrl = "https://api.openai.com" | "https://api.together.xyz";
+type ChatRequestProviders = {
+    provider: "openai";
+    model: OpenAIChatModel;
+    llmToken: string;
+} | {
+    provider: "togetherai";
+    model: TogetherAIChatModel;
+    llmToken: string;
+} | {
+    provider: "upstash";
+    model: ChatModel;
+};
+type PromptChatRequest<TStream extends StreamParameter> = ChatRequestProviders & PromptChatRequestFields & TStream;
+type ChatRequest<TStream extends StreamParameter> = ChatRequestProviders & ChatRequestFields & TStream;
 
 type UpstashRequest = {
     /**
@@ -198,7 +224,7 @@ type UpstashRequest = {
     /**
      * A string to set request's method.
      */
-    method?: "GET" | "POST" | "PUT" | "DELETE";
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
     query?: Record<string, string | number | boolean | undefined>;
     /**
      * if enabled, call `res.json()`
@@ -206,6 +232,7 @@ type UpstashRequest = {
      * @default true
      */
     parseResponseAsJson?: boolean;
+    baseUrl?: string;
 };
 type UpstashResponse<TResult> = TResult & {
     error?: string;
@@ -238,9 +265,9 @@ type Message = {
      */
     messageId: string;
     /**
-     * The topic name if this message was sent to a topic.
+     * The url group name if this message was sent to a urlGroup.
      */
-    topicName?: string;
+    urlGroup?: string;
     /**
      * The url where this message is sent to.
      */
@@ -282,6 +309,9 @@ type Message = {
      */
     queueName?: string;
 };
+type MessagePayload = Omit<Message, "urlGroup"> & {
+    topicName: string;
+};
 declare class Messages {
     private readonly http;
     constructor(http: Requester);
@@ -330,9 +360,22 @@ type QueueResponse = {
     name: string;
     parallelism: number;
     lag: number;
+    paused?: boolean;
 };
 type UpsertQueueRequest = {
-    parallelism: number;
+    /**
+     * The number of parallel consumers consuming from the queue.
+     *
+     * @default 1
+     */
+    parallelism?: number;
+    /**
+     * Whether to pause the queue or not. A paused queue will not
+     * deliver new messages until it is resumed.
+     *
+     * @default false
+     */
+    paused?: boolean;
 };
 declare class Queue {
     private readonly http;
@@ -362,6 +405,17 @@ declare class Queue {
      * Enqueue a message to a queue, serializing the body to JSON.
      */
     enqueueJSON<TBody = unknown, TRequest extends PublishRequest<TBody> = PublishRequest<TBody>>(request: TRequest): Promise<PublishResponse<TRequest>>;
+    /**
+     * Pauses the queue.
+     *
+     * A paused queue will not deliver messages until
+     * it is resumed.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resumes the queue.
+     */
+    resume(): Promise<void>;
 }
 
 type Schedule = {
@@ -376,10 +430,11 @@ type Schedule = {
     delay?: number;
     callback?: string;
     failureCallback?: string;
+    isPaused: true | undefined;
 };
 type CreateScheduleRequest = {
     /**
-     * Either a URL or topic name
+     * Either a URL or urlGroup name
      */
     destination: string;
     /**
@@ -441,6 +496,17 @@ type CreateScheduleRequest = {
      * Specify a cron expression to repeatedly send this message to the destination.
      */
     cron: string;
+    /**
+     * The HTTP timeout value to use while calling the destination URL.
+     * When a timeout is specified, it will be used instead of the maximum timeout
+     * value permitted by the QStash plan. It is useful in scenarios, where a message
+     * should be delivered with a shorter timeout.
+     *
+     * In seconds.
+     *
+     * @default undefined
+     */
+    timeout?: number;
 };
 declare class Schedules {
     private readonly http;
@@ -463,6 +529,21 @@ declare class Schedules {
      * Delete a schedule
      */
     delete(scheduleId: string): Promise<void>;
+    /**
+     * Pauses the schedule.
+     *
+     * A paused schedule will not deliver messages until
+     * it is resumed.
+     */
+    pause({ schedule }: {
+        schedule: string;
+    }): Promise<void>;
+    /**
+     * Resumes the schedule.
+     */
+    resume({ schedule }: {
+        schedule: string;
+    }): Promise<void>;
 }
 
 type Endpoint = {
@@ -477,7 +558,7 @@ type Endpoint = {
 };
 type AddEndpointsRequest = {
     /**
-     * The name of the topic.
+     * The name of the url group.
      * Must be unique and only contain alphanumeric, hyphen, underscore and periods.
      */
     name: string;
@@ -485,7 +566,7 @@ type AddEndpointsRequest = {
 };
 type RemoveEndpointsRequest = {
     /**
-     * The name of the topic.
+     * The name of the url group.
      * Must be unique and only contain alphanumeric, hyphen, underscore and periods.
      */
     name: string;
@@ -497,7 +578,7 @@ type RemoveEndpointsRequest = {
         url: string;
     })[];
 };
-type Topic = {
+type UrlGroup = {
     /**
      * A unix timestamp (milliseconds)
      */
@@ -507,7 +588,7 @@ type Topic = {
      */
     updatedAt: number;
     /**
-     * The name of this topic.
+     * The name of this url group.
      */
     name: string;
     /**
@@ -515,27 +596,27 @@ type Topic = {
      */
     endpoints: Endpoint[];
 };
-declare class Topics {
+declare class UrlGroups {
     private readonly http;
     constructor(http: Requester);
     /**
-     * Create a new topic with the given name and endpoints
+     * Create a new url group with the given name and endpoints
      */
     addEndpoints(request: AddEndpointsRequest): Promise<void>;
     /**
-     * Remove endpoints from a topic.
+     * Remove endpoints from a url group.
      */
     removeEndpoints(request: RemoveEndpointsRequest): Promise<void>;
     /**
-     * Get a list of all topics.
+     * Get a list of all url groups.
      */
-    list(): Promise<Topic[]>;
+    list(): Promise<UrlGroup[]>;
     /**
-     * Get a single topic
+     * Get a single url group
      */
-    get(name: string): Promise<Topic>;
+    get(name: string): Promise<UrlGroup>;
     /**
-     * Delete a topic
+     * Delete a url group
      */
     delete(name: string): Promise<void>;
 }
@@ -554,6 +635,16 @@ declare class Chat {
      * @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.
      *
@@ -565,7 +656,7 @@ declare class Chat {
      *    mistralai/Mistral-7B-Instruct-v0.2 model.
      * @returns Chat completion or stream
      */
-    prompt: <TStream extends StreamParameter>(request: PromptRequest<TStream>) => Promise<TStream extends StreamEnabled ? AsyncIterable<ChatCompletionChunk> : ChatCompletion>;
+    prompt: <TStream extends StreamParameter>(request: PromptChatRequest<TStream>) => Promise<TStream extends StreamEnabled ? AsyncIterable<ChatCompletionChunk> : ChatCompletion>;
 }
 
 type ClientConfig = {
@@ -684,27 +775,56 @@ type PublishRequest<TBody = BodyInit> = {
      * @default `POST`
      */
     method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /**
+     * The HTTP timeout value to use while calling the destination URL.
+     * When a timeout is specified, it will be used instead of the maximum timeout
+     * value permitted by the QStash plan. It is useful in scenarios, where a message
+     * should be delivered with a shorter timeout.
+     *
+     * In seconds.
+     *
+     * @default undefined
+     */
+    timeout?: number;
 } & ({
     /**
      * The url where the message should be sent to.
      */
     url: string;
-    topic?: never;
+    urlGroup?: never;
     api?: never;
+    llmProvider?: never;
 } | {
     url?: never;
     /**
-     * The topic the message should be sent to.
+     * The url group the message should be sent to.
      */
-    topic: string;
+    urlGroup: string;
     api?: never;
+    llmProvider?: never;
 } | {
     url?: never;
-    topic?: never;
+    urlGroup?: never;
     /**
      * The api endpoint the request should be sent to.
      */
     api: "llm";
+    llmProvider?: never;
+} | {
+    /**
+     * 3rd party provider url such as OpenAI: https://api.openai.com/v1/chat/completions
+     */
+    url?: string;
+    urlGroup?: never;
+    api?: never;
+    /**
+     * 3rd party provider name such as OpenAI, TogetherAI
+     */
+    llmProvider: LlmProvider;
+    /**
+     * 3rd party provider secret key
+     */
+    llmToken?: string;
 });
 type PublishJsonRequest = Omit<PublishRequest, "body"> & {
     /**
@@ -721,7 +841,7 @@ type EventsRequestFilter = {
     messageId?: string;
     state?: State;
     url?: string;
-    topicName?: string;
+    urlGroup?: string;
     scheduleId?: string;
     queueName?: string;
     fromDate?: number;
@@ -739,11 +859,11 @@ declare class Client {
     http: Requester;
     constructor(config: ClientConfig);
     /**
-     * Access the topic API.
+     * Access the urlGroup API.
      *
-     * Create, read, update or delete topics.
+     * Create, read, update or delete urlGroups.
      */
-    get topics(): Topics;
+    get urlGroups(): UrlGroups;
     /**
      * Access the dlq API.
      *
@@ -816,12 +936,12 @@ type PublishToUrlResponse = PublishToApiResponse & {
     url: string;
     deduplicated?: boolean;
 };
-type PublishToTopicResponse = PublishToUrlResponse[];
+type PublishToUrlGroupsResponse = PublishToUrlResponse[];
 type PublishResponse<TRequest> = TRequest extends {
     url: string;
 } ? PublishToUrlResponse : TRequest extends {
-    topic: string;
-} ? PublishToTopicResponse : PublishToApiResponse;
+    urlGroup: string;
+} ? PublishToUrlGroupsResponse : PublishToApiResponse;
 
 /**
  * Result of 500 Internal Server Error
@@ -836,4 +956,4 @@ declare class QstashChatRatelimitError extends QstashError {
     constructor(args: ChatRateLimit);
 }
 
-export { type AddEndpointsRequest, type BodyInit, Chat, type ChatCompletion, type ChatCompletionChunk, type ChatCompletionMessage, type ChatRateLimit, type ChatRequest, Client, type CreateScheduleRequest, type Endpoint, type Event, type EventsRequest, type GetEventsResponse, type HeadersInit, type Message, Messages, type PromptRequest, type PublishBatchRequest, type PublishJsonRequest, type PublishRequest, type PublishResponse, type PublishToApiResponse, type PublishToTopicResponse, 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 Topic, Topics, 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 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 };