Cogover Learning

API reference @cogover/sdk: Push message

Trang này thuộc API reference của @cogover/sdk.

Push message

push gửi message tới web client của workspace: yêu cầu tải lại record, một toast, hoặc một message chạy ngầm mà client tự xử lý. Đây là cùng cơ chế với action "Push Message" của Workflow, nên trang record chuẩn phản ứng mà không cần code client. Gửi là best-effort: lời gọi hoàn tất khi message đã được bàn giao cho Cogover, không phải khi client nhận được. 

type PushRecipients = "viewers" | readonly string[];
 
interface PushOptions {
  readonly recipients?: PushRecipients;
  readonly exclude?: readonly string[];
}
 
type ToastPosition = "TOP_LEFT" | "TOP_CENTER" | "TOP_RIGHT"
  | "BOTTOM_LEFT" | "BOTTOM_CENTER" | "BOTTOM_RIGHT";
type ToastSize = "SMALL" | "MEDIUM" | "LARGE";
 
interface ToastLink {
  readonly label: string;
  readonly url: string;
}
 
interface ToastMessage<ObjectSlug extends string = string> {
  readonly title?: string;
  readonly content?: string;
  readonly links?: readonly ToastLink[];
  readonly position?: ToastPosition;
  readonly size?: ToastSize;
  readonly durationSeconds?: number;
  readonly object?: ObjectSlug;
  readonly recordIds?: readonly string[];
}
 
type BackgroundContentType = "text" | "template";
 
interface BackgroundMessage<ObjectSlug extends string = string> {
  readonly content: string;
  readonly contentType?: BackgroundContentType;
  readonly object?: ObjectSlug;
  readonly recordIds?: readonly string[];
}
 
interface PushApi<Schema extends object = EffectiveWorkspaceObjects> {
  refreshRecords(object: StringKeyOf<Schema>, recordIds: readonly string[],
    options?: PushOptions): Promise<void>;
  toast(message: ToastMessage<StringKeyOf<Schema>>, options?: PushOptions): Promise<void>;
  message(message: BackgroundMessage<StringKeyOf<Schema>>, options?: PushOptions): Promise<void>;
}
// Trigger after-change: handler đã sửa record nên mọi người đang mở record phải tải
// lại, kể cả người vừa lưu và làm trigger chạy.
await data.object("order").records.batchUpdate(items);
await push.refreshRecords("order", items.map(item => item.id));

Người nhận

Mọi method nhận cùng options. recipients mặc định là "viewers": mọi người đang mở một trong các record đích sẽ nhận message, vì vậy object và recordIds là bắt buộc. Danh sách personnel ID gửi tới đúng những người đó dù họ đang ở đâu trong workspace; khi đó object và recordIds là tuỳ chọn với toast và message, và nếu có thì cho client biết message nói về record nào. exclude liệt kê personnel ID không bao giờ nhận message; giá trị đặc biệt "actor" là người dùng có hành động khởi đầu execution hiện tại (người gọi HTTP script, người lưu record làm trigger chạy). Execution hệ thống không có actor nên "actor" không loại ai. Personnel chưa có tài khoản người dùng được bỏ qua; personnel ID hoặc object slug không tồn tại ném NotFoundError trước khi gửi bất kỳ message nào. recordIds nhận tối đa 200 record ID khác nhau, còn recipients và exclude mỗi danh sách tối đa 200 phần tử, đếm trước khi loại trùng; sau đó ID trùng được loại bỏ. Cogover không kiểm tra record ID có tồn tại hay không: message về record không tồn tại sẽ không tới ai đang xem.

push.refreshRecords(object, recordIds, options?): Promise<void>

Yêu cầu các client đang hiển thị những record này tải lại chúng. Trang record của web app tự xử lý yêu cầu. recordIds nhận 1 đến 200 ID.

push.toast(message, options?): Promise<void>

Hiển thị một thông báo ngắn. Cần ít nhất một trong title (tối đa 200 ký tự) và content (tối đa 4.000 ký tự). links chứa tối đa 5 mục với url là URL tuyệt đối http hoặc https. position mặc định "TOP_RIGHT", size mặc định "MEDIUM" và durationSeconds mặc định 5 (từ 1 đến 60). Khi có object và recordIds, client chỉ hiển thị toast trong lúc một trong các record đó đang mở.

push.message(message, options?): Promise<void>

Gửi một message mà client xử lý không kèm thông báo hiển thị, ví dụ một custom component đang lắng nghe. content là bắt buộc (tối đa 16.384 ký tự); contentType là "text" (mặc định) hoặc "template".

Quy tắc

  • Mỗi lời gọi tốn một capability call bất kể số record hay người nhận; khi người nhận là "viewers", mỗi record được gửi một message.
  • Input được SDK kiểm tra và Cogover kiểm tra lại; input không hợp lệ ném ValidationError trước khi gửi bất kỳ message nào.
  • push có trong script, route, trigger after-change và Development Session. Trigger before-change là chỉ đọc và nhận PermissionDeniedError với reason TRIGGER_READ_ONLY; Development Session chỉ đọc cũng từ chối.
  • Khi deployment tắt push message, mọi lời gọi ném CogoverApiError với code PUSH_DISABLED; HTTP route không bắt lỗi này sẽ trả response HTTP 422 chung.
  • Message đã gửi không thể thu hồi, và chạy lại một execution thất bại có thể gửi lại message.

© 2026 Cogover LLC