linger_openai_sdk/
chatkit.rs

1use crate::LingerError;
2use crate::RequestId;
3use serde::{Deserialize, Serialize};
4use serde_json::Value;
5
6/// EN: ChatKit session returned by the ChatKit beta API.
7/// 中文：ChatKit beta API 返回的 ChatKit session。
8#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
9#[non_exhaustive]
10pub struct ChatKitSession {
11    /// EN: Identifier for the ChatKit session.
12    /// 中文：ChatKit session 标识符。
13    pub id: String,
14    /// EN: API object type, normally `chatkit.session`.
15    /// 中文：API 对象类型，通常为 `chatkit.session`。
16    pub object: String,
17    /// EN: Unix timestamp for when the session expires.
18    /// 中文：session 过期时间的 Unix 时间戳。
19    pub expires_at: u64,
20    /// EN: Ephemeral client secret that authenticates session requests.
21    /// 中文：用于认证 session 请求的临时 client secret。
22    pub client_secret: String,
23    /// EN: Workflow metadata for the session.
24    /// 中文：session 的 workflow 元数据。
25    pub workflow: ChatKitWorkflow,
26    /// EN: User identifier associated with the session.
27    /// 中文：与 session 关联的用户标识符。
28    pub user: String,
29    /// EN: Resolved rate limit values.
30    /// 中文：解析后的速率限制值。
31    pub rate_limits: ChatKitSessionRateLimits,
32    /// EN: Convenience copy of the per-minute request limit.
33    /// 中文：每分钟请求限制的便捷副本。
34    pub max_requests_per_1_minute: u64,
35    /// EN: Current lifecycle state of the session.
36    /// 中文：session 当前生命周期状态。
37    pub status: String,
38    /// EN: Resolved ChatKit feature configuration.
39    /// 中文：解析后的 ChatKit 功能配置。
40    pub chatkit_configuration: Value,
41    /// EN: OpenAI request id from response headers.
42    /// 中文：响应头中的 OpenAI 请求 ID。
43    #[serde(skip)]
44    request_id: Option<RequestId>,
45}
46
47impl ChatKitSession {
48    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
49        self.request_id = request_id;
50        self
51    }
52
53    /// EN: Returns the OpenAI request id, when present.
54    /// 中文：返回 OpenAI 请求 ID，如存在。
55    pub fn request_id(&self) -> Option<&RequestId> {
56        self.request_id.as_ref()
57    }
58}
59
60/// EN: ChatKit thread returned by the ChatKit beta API.
61/// 中文：ChatKit beta API 返回的 ChatKit thread。
62#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
63#[non_exhaustive]
64pub struct ChatKitThread {
65    /// EN: Identifier for the ChatKit thread.
66    /// 中文：ChatKit thread 标识符。
67    pub id: String,
68    /// EN: API object type, normally `chatkit.thread`.
69    /// 中文：API 对象类型，通常为 `chatkit.thread`。
70    pub object: String,
71    /// EN: Unix timestamp for when the thread was created.
72    /// 中文：thread 创建时间的 Unix 时间戳。
73    pub created_at: u64,
74    /// EN: Optional human-readable thread title.
75    /// 中文：可选的人类可读 thread 标题。
76    pub title: Option<String>,
77    /// EN: Current status object for the thread.
78    /// 中文：thread 当前状态对象。
79    pub status: Value,
80    /// EN: End-user identifier that owns the thread.
81    /// 中文：拥有该 thread 的最终用户标识符。
82    pub user: String,
83    /// EN: OpenAI request id from response headers.
84    /// 中文：响应头中的 OpenAI 请求 ID。
85    #[serde(skip)]
86    request_id: Option<RequestId>,
87}
88
89impl ChatKitThread {
90    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
91        self.request_id = request_id;
92        self
93    }
94
95    /// EN: Returns the OpenAI request id, when present.
96    /// 中文：返回 OpenAI 请求 ID，如存在。
97    pub fn request_id(&self) -> Option<&RequestId> {
98        self.request_id.as_ref()
99    }
100}
101
102/// EN: Deletion result returned by the ChatKit Threads API.
103/// 中文：ChatKit Threads API 返回的删除结果。
104#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
105#[non_exhaustive]
106pub struct ChatKitThreadDeletion {
107    /// EN: Deleted ChatKit thread id.
108    /// 中文：已删除的 ChatKit thread ID。
109    pub id: String,
110    /// EN: API object type, normally `chatkit.thread.deleted`.
111    /// 中文：API 对象类型，通常为 `chatkit.thread.deleted`。
112    pub object: String,
113    /// EN: Whether the ChatKit thread was deleted.
114    /// 中文：ChatKit thread 是否已删除。
115    pub deleted: bool,
116    /// EN: OpenAI request id from response headers.
117    /// 中文：响应头中的 OpenAI 请求 ID。
118    #[serde(skip)]
119    request_id: Option<RequestId>,
120}
121
122impl ChatKitThreadDeletion {
123    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
124        self.request_id = request_id;
125        self
126    }
127
128    /// EN: Returns the OpenAI request id, when present.
129    /// 中文：返回 OpenAI 请求 ID，如存在。
130    pub fn request_id(&self) -> Option<&RequestId> {
131        self.request_id.as_ref()
132    }
133}
134
135/// EN: Page of ChatKit threads returned by `GET /v1/chatkit/threads`.
136/// 中文：`GET /v1/chatkit/threads` 返回的 ChatKit thread 分页。
137#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
138#[non_exhaustive]
139pub struct ChatKitThreadPage {
140    /// EN: API object type, normally `list`.
141    /// 中文：API 对象类型，通常为 `list`。
142    pub object: String,
143    /// EN: ChatKit threads in this page.
144    /// 中文：当前分页中的 ChatKit threads。
145    pub data: Vec<ChatKitThread>,
146    /// EN: First thread id in this page, when present.
147    /// 中文：当前分页中的第一个 thread ID，如存在。
148    pub first_id: Option<String>,
149    /// EN: Last thread id in this page, when present.
150    /// 中文：当前分页中的最后一个 thread ID，如存在。
151    pub last_id: Option<String>,
152    /// EN: Whether more threads are available.
153    /// 中文：是否还有更多 threads 可用。
154    pub has_more: bool,
155    /// EN: OpenAI request id from response headers.
156    /// 中文：响应头中的 OpenAI 请求 ID。
157    #[serde(skip)]
158    request_id: Option<RequestId>,
159}
160
161impl ChatKitThreadPage {
162    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
163        self.request_id = request_id;
164        self
165    }
166
167    /// EN: Returns the OpenAI request id, when present.
168    /// 中文：返回 OpenAI 请求 ID，如存在。
169    pub fn request_id(&self) -> Option<&RequestId> {
170        self.request_id.as_ref()
171    }
172}
173
174/// EN: Page of ChatKit thread items returned by `GET /v1/chatkit/threads/{thread_id}/items`.
175/// 中文：`GET /v1/chatkit/threads/{thread_id}/items` 返回的 ChatKit thread item 分页。
176#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
177#[non_exhaustive]
178pub struct ChatKitThreadItemPage {
179    /// EN: API object type, normally `list`.
180    /// 中文：API 对象类型，通常为 `list`。
181    pub object: String,
182    /// EN: Raw ChatKit thread items in this page.
183    /// 中文：当前分页中的原始 ChatKit thread items。
184    pub data: Vec<Value>,
185    /// EN: First item id in this page, when present.
186    /// 中文：当前分页中的第一个 item ID，如存在。
187    pub first_id: Option<String>,
188    /// EN: Last item id in this page, when present.
189    /// 中文：当前分页中的最后一个 item ID，如存在。
190    pub last_id: Option<String>,
191    /// EN: Whether more items are available.
192    /// 中文：是否还有更多 items 可用。
193    pub has_more: bool,
194    /// EN: OpenAI request id from response headers.
195    /// 中文：响应头中的 OpenAI 请求 ID。
196    #[serde(skip)]
197    request_id: Option<RequestId>,
198}
199
200impl ChatKitThreadItemPage {
201    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
202        self.request_id = request_id;
203        self
204    }
205
206    /// EN: Returns the OpenAI request id, when present.
207    /// 中文：返回 OpenAI 请求 ID，如存在。
208    pub fn request_id(&self) -> Option<&RequestId> {
209        self.request_id.as_ref()
210    }
211}
212
213/// EN: Workflow metadata on a ChatKit session.
214/// 中文：ChatKit session 上的 workflow 元数据。
215#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
216#[non_exhaustive]
217pub struct ChatKitWorkflow {
218    /// EN: Workflow identifier.
219    /// 中文：workflow 标识符。
220    pub id: String,
221    /// EN: Workflow version, when returned.
222    /// 中文：返回的 workflow 版本。
223    pub version: Option<String>,
224}
225
226/// EN: Rate limit values on a ChatKit session.
227/// 中文：ChatKit session 上的速率限制值。
228#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
229#[non_exhaustive]
230pub struct ChatKitSessionRateLimits {
231    /// EN: Maximum requests per one minute.
232    /// 中文：每一分钟最大请求数。
233    pub max_requests_per_1_minute: u64,
234}
235
236/// EN: Request body for `POST /v1/chatkit/sessions`.
237/// 中文：`POST /v1/chatkit/sessions` 的请求体。
238#[derive(Clone, Debug, Serialize, PartialEq)]
239#[non_exhaustive]
240pub struct CreateChatKitSessionRequest {
241    /// EN: Workflow that powers the session.
242    /// 中文：驱动 session 的 workflow。
243    pub workflow: ChatKitWorkflowParam,
244    /// EN: End-user identifier for the session.
245    /// 中文：session 的最终用户标识符。
246    pub user: String,
247    /// EN: Optional session expiration override.
248    /// 中文：可选的 session 过期时间覆盖。
249    #[serde(skip_serializing_if = "Option::is_none")]
250    pub expires_after: Option<ChatKitSessionExpiration>,
251    /// EN: Optional request rate limit overrides.
252    /// 中文：可选的请求速率限制覆盖。
253    #[serde(skip_serializing_if = "Option::is_none")]
254    pub rate_limits: Option<ChatKitSessionRateLimitOverrides>,
255    /// EN: Optional ChatKit runtime configuration overrides.
256    /// 中文：可选的 ChatKit 运行时配置覆盖。
257    #[serde(skip_serializing_if = "Option::is_none")]
258    pub chatkit_configuration: Option<Value>,
259}
260
261impl CreateChatKitSessionRequest {
262    /// EN: Returns a builder for ChatKit session create requests.
263    /// 中文：返回 ChatKit session 创建请求构建器。
264    pub fn builder() -> CreateChatKitSessionRequestBuilder {
265        CreateChatKitSessionRequestBuilder::default()
266    }
267}
268
269/// EN: Builder for `CreateChatKitSessionRequest`.
270/// 中文：`CreateChatKitSessionRequest` 的构建器。
271#[derive(Clone, Debug, Default)]
272pub struct CreateChatKitSessionRequestBuilder {
273    workflow: Option<ChatKitWorkflowParam>,
274    user: Option<String>,
275    expires_after: Option<ChatKitSessionExpiration>,
276    rate_limits: Option<ChatKitSessionRateLimitOverrides>,
277    chatkit_configuration: Option<Value>,
278}
279
280impl CreateChatKitSessionRequestBuilder {
281    /// EN: Sets the workflow that powers the session.
282    /// 中文：设置驱动 session 的 workflow。
283    pub fn workflow(mut self, workflow: ChatKitWorkflowParam) -> Self {
284        self.workflow = Some(workflow);
285        self
286    }
287
288    /// EN: Sets the end-user identifier.
289    /// 中文：设置最终用户标识符。
290    pub fn user(mut self, user: impl Into<String>) -> Self {
291        self.user = Some(user.into());
292        self
293    }
294
295    /// EN: Sets the session expiration override.
296    /// 中文：设置 session 过期时间覆盖。
297    pub fn expires_after(mut self, expires_after: ChatKitSessionExpiration) -> Self {
298        self.expires_after = Some(expires_after);
299        self
300    }
301
302    /// EN: Sets the request rate limit overrides.
303    /// 中文：设置请求速率限制覆盖。
304    pub fn rate_limits(mut self, rate_limits: ChatKitSessionRateLimitOverrides) -> Self {
305        self.rate_limits = Some(rate_limits);
306        self
307    }
308
309    /// EN: Sets ChatKit runtime configuration overrides.
310    /// 中文：设置 ChatKit 运行时配置覆盖。
311    pub fn chatkit_configuration(mut self, chatkit_configuration: Value) -> Self {
312        self.chatkit_configuration = Some(chatkit_configuration);
313        self
314    }
315
316    /// EN: Builds a validated ChatKit session create request.
317    /// 中文：构建经过校验的 ChatKit session 创建请求。
318    pub fn build(self) -> Result<CreateChatKitSessionRequest, LingerError> {
319        let workflow = self
320            .workflow
321            .ok_or_else(|| LingerError::invalid_config("workflow is required"))?;
322        let user = self
323            .user
324            .ok_or_else(|| LingerError::invalid_config("user is required"))?;
325        if user.trim().is_empty() {
326            return Err(LingerError::invalid_config("user must not be empty"));
327        }
328        Ok(CreateChatKitSessionRequest {
329            workflow,
330            user,
331            expires_after: self.expires_after,
332            rate_limits: self.rate_limits,
333            chatkit_configuration: self.chatkit_configuration,
334        })
335    }
336}
337
338/// EN: Workflow reference and overrides for a ChatKit session.
339/// 中文：ChatKit session 的 workflow 引用和覆盖。
340#[derive(Clone, Debug, Serialize, PartialEq)]
341#[non_exhaustive]
342pub struct ChatKitWorkflowParam {
343    /// EN: Workflow identifier.
344    /// 中文：workflow 标识符。
345    pub id: String,
346    /// EN: Specific workflow version to run.
347    /// 中文：要运行的特定 workflow 版本。
348    #[serde(skip_serializing_if = "Option::is_none")]
349    pub version: Option<String>,
350    /// EN: State variables forwarded to the workflow.
351    /// 中文：转发给 workflow 的状态变量。
352    #[serde(skip_serializing_if = "Option::is_none")]
353    pub state_variables: Option<Value>,
354    /// EN: Optional tracing overrides.
355    /// 中文：可选 tracing 覆盖。
356    #[serde(skip_serializing_if = "Option::is_none")]
357    pub tracing: Option<Value>,
358}
359
360impl ChatKitWorkflowParam {
361    /// EN: Creates a workflow reference with the required id.
362    /// 中文：使用必需的 id 创建 workflow 引用。
363    pub fn new(id: impl Into<String>) -> Self {
364        Self {
365            id: id.into(),
366            version: None,
367            state_variables: None,
368            tracing: None,
369        }
370    }
371
372    /// EN: Sets the workflow version.
373    /// 中文：设置 workflow 版本。
374    pub fn version(mut self, version: impl Into<String>) -> Self {
375        self.version = Some(version.into());
376        self
377    }
378
379    /// EN: Sets state variables forwarded to the workflow.
380    /// 中文：设置转发给 workflow 的状态变量。
381    pub fn state_variables(mut self, state_variables: Value) -> Self {
382        self.state_variables = Some(state_variables);
383        self
384    }
385
386    /// EN: Sets tracing overrides.
387    /// 中文：设置 tracing 覆盖。
388    pub fn tracing(mut self, tracing: Value) -> Self {
389        self.tracing = Some(tracing);
390        self
391    }
392}
393
394/// EN: ChatKit session expiration override.
395/// 中文：ChatKit session 过期时间覆盖。
396#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
397#[non_exhaustive]
398pub struct ChatKitSessionExpiration {
399    /// EN: Base timestamp used to calculate expiration.
400    /// 中文：用于计算过期时间的基准时间戳。
401    pub anchor: String,
402    /// EN: Number of seconds after the anchor when the session expires.
403    /// 中文：基准时间戳之后 session 过期的秒数。
404    pub seconds: u64,
405}
406
407impl ChatKitSessionExpiration {
408    /// EN: Creates an expiration override anchored at `created_at`.
409    /// 中文：创建以 `created_at` 为基准的过期时间覆盖。
410    pub fn created_at(seconds: u64) -> Self {
411        Self {
412            anchor: "created_at".to_string(),
413            seconds,
414        }
415    }
416}
417
418/// EN: ChatKit session rate limit overrides.
419/// 中文：ChatKit session 速率限制覆盖。
420#[derive(Clone, Debug, Default, Serialize, PartialEq, Eq)]
421#[non_exhaustive]
422pub struct ChatKitSessionRateLimitOverrides {
423    /// EN: Maximum requests per one minute.
424    /// 中文：每一分钟最大请求数。
425    #[serde(skip_serializing_if = "Option::is_none")]
426    pub max_requests_per_1_minute: Option<u64>,
427}
428
429impl ChatKitSessionRateLimitOverrides {
430    /// EN: Creates empty rate limit overrides.
431    /// 中文：创建空的速率限制覆盖。
432    pub fn new() -> Self {
433        Self::default()
434    }
435
436    /// EN: Sets the maximum requests per one minute.
437    /// 中文：设置每一分钟最大请求数。
438    pub fn max_requests_per_1_minute(mut self, max_requests_per_1_minute: u64) -> Self {
439        self.max_requests_per_1_minute = Some(max_requests_per_1_minute);
440        self
441    }
442}
linger_openai_sdk/chatkit.rs

linger_openai_sdk/
chatkit.rs
