@nemphi/sdk 0.2.5277 → 0.3.5333

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -577,9 +577,9 @@ export interface Notification {
577
577
  seq?: number;
578
578
  }
579
579
  /**
580
- * One realtime event of the workspace (`openRealtimeSocket`, which polls
581
- * `GET /v1/events/poll`; the frames of `GET /v1/events/stream` and
582
- * `GET /v1/events/socket`).
580
+ * One realtime event of the workspace (`openRealtimeSocket` and
581
+ * `streamEvents`, the frames of `GET /v1/events/stream` and
582
+ * `GET /v1/events/socket`), or of one chat thread (`streamThread`).
583
583
  * `action` and `notification` are wakeups — re-read the surface, the row
584
584
  * itself comes by cursor; the rest is state that only matters while
585
585
  * someone is watching.
@@ -653,6 +653,13 @@ export type RealtimeEvent = {
653
653
  /** ISO instant after which a reader drops them unless the signal repeats. */
654
654
  until: string;
655
655
  };
656
+ /**
657
+ * One frame of a chat thread's own stream (`streamThread`): a piece of the
658
+ * answer a run is writing (`run_delta`), or a run step's end (`run`).
659
+ */
660
+ export type ThreadStreamEvent = Extract<RealtimeEvent, {
661
+ type: "run" | "run_delta";
662
+ }>;
656
663
  /** Where a person is typing: a chat thread or a marketing inbox conversation. */
657
664
  export type TypingScope = Extract<RealtimeEvent, {
658
665
  type: "typing";
@@ -671,7 +678,7 @@ export interface RealtimeSocketOptions {
671
678
  /** Called when a poll fails after one answered. */
672
679
  onClose?: () => void;
673
680
  /**
674
- * Ignored: the subscription polls `GET /v1/events/poll` over `fetch`
681
+ * Ignored: the subscription reads `GET /v1/events/stream` over `fetch`
675
682
  * rather than holding a WebSocket. Kept so existing callers compile.
676
683
  */
677
684
  webSocket?: (url: string, headers: Record<string, string>) => WebSocket;
@@ -5109,6 +5116,55 @@ export interface MarketingInboxTopic {
5109
5116
  description?: string;
5110
5117
  }
5111
5118
  /** An inbox conversation on a connected marketing channel (WhatsApp Business threads today). */
5119
+ /** A public comment under an Instagram or Facebook post, or a reply sent from the inbox. */
5120
+ export interface MarketingComment {
5121
+ id: string;
5122
+ channel_id: string;
5123
+ post_id: string | null;
5124
+ external_id: string;
5125
+ parent_external_id: string;
5126
+ author_name: string;
5127
+ body: string;
5128
+ direction: "in" | "out";
5129
+ status: "received" | "pending" | "sent" | "failed";
5130
+ hidden: boolean;
5131
+ error: string;
5132
+ commented_at: string;
5133
+ post_caption: string | null;
5134
+ post_url: string | null;
5135
+ }
5136
+ /** A private note teammates left on an inbox thread. */
5137
+ export interface MarketingConversationNote {
5138
+ id: string;
5139
+ author_user_id: string | null;
5140
+ author_name: string;
5141
+ body: string;
5142
+ created_at: string;
5143
+ }
5144
+ /** An internal comment a teammate left on a post. */
5145
+ export interface MarketingPostNote {
5146
+ id: string;
5147
+ author_user_id: string | null;
5148
+ author_name: string;
5149
+ body: string;
5150
+ created_at: string;
5151
+ }
5152
+ /** A post idea in the workspace's backlog. */
5153
+ export interface MarketingIdea {
5154
+ id: string;
5155
+ title: string;
5156
+ notes: string;
5157
+ created_at: string;
5158
+ updated_at: string;
5159
+ }
5160
+ /** A saved caption or hashtag group the composer inserts. */
5161
+ export interface MarketingSnippet {
5162
+ id: string;
5163
+ kind: "caption" | "hashtags";
5164
+ name: string;
5165
+ body: string;
5166
+ updated_at: string;
5167
+ }
5112
5168
  export interface MarketingConversation {
5113
5169
  id: string;
5114
5170
  channel_id: string;
@@ -5119,6 +5175,8 @@ export interface MarketingConversation {
5119
5175
  peer_phone: string;
5120
5176
  peer_name: string;
5121
5177
  party_id?: string | null;
5178
+ /** The teammate who owns the thread. */
5179
+ assignee_user_id?: string;
5122
5180
  last_message_at: string | null;
5123
5181
  last_direction?: "inbound" | "outbound";
5124
5182
  last_snippet: string;
@@ -5553,6 +5611,75 @@ export interface MarketingPost {
5553
5611
  channel_name?: string;
5554
5612
  /** The TikTok direct-post choices a TikTok post carries, as TikTok's `post_info` names them. */
5555
5613
  tiktok?: MarketingPostTikTokSettings | null;
5614
+ /** The Instagram and Facebook extras: first comment, alt text, collaborators. */
5615
+ details?: MarketingPostDetails | null;
5616
+ /** The workspace's own labels for the post; never published. */
5617
+ tags?: string[];
5618
+ }
5619
+ /** What an Instagram or Facebook post carries beside its caption. */
5620
+ export interface MarketingPostDetails {
5621
+ first_comment?: string;
5622
+ alt_text?: string;
5623
+ collaborators?: string[];
5624
+ }
5625
+ /** The extras `marketing.create_post` and `marketing.save_post_draft` take. */
5626
+ export interface MarketingPostDetailChoices {
5627
+ first_comment?: string;
5628
+ alt_text?: string;
5629
+ collaborators?: string[];
5630
+ }
5631
+ /** A caption the AI wrote for one network. */
5632
+ export interface MarketingCaptionSuggestion {
5633
+ provider: string;
5634
+ caption: string;
5635
+ }
5636
+ /** A request for AI captions and, once done, one suggestion per network. */
5637
+ export interface MarketingCaptionDraft {
5638
+ id: string;
5639
+ status: "queued" | "done" | "failed";
5640
+ brief: string;
5641
+ tone: string;
5642
+ providers: string[];
5643
+ suggestions: MarketingCaptionSuggestion[];
5644
+ /** Starts with a code: allowance_used, not_configured or failed. */
5645
+ error: string;
5646
+ created_at: string;
5647
+ finished_at: string | null;
5648
+ }
5649
+ /** A generated picture or video request; url is set once it is done. */
5650
+ export interface MarketingGeneration {
5651
+ id: string;
5652
+ kind: "image" | "video";
5653
+ status: "queued" | "rendering" | "done" | "failed";
5654
+ prompt: string;
5655
+ url: string | null;
5656
+ error: string;
5657
+ created_at: string;
5658
+ }
5659
+ /** One weekly posting time: 0 Sunday … 6 Saturday, and a local "HH:MM". */
5660
+ export interface MarketingPostScheduleSlot {
5661
+ weekday: number;
5662
+ time: string;
5663
+ }
5664
+ /** An account's weekly posting times and the next one no post has taken. */
5665
+ export interface MarketingPostSchedule {
5666
+ channel_id: string;
5667
+ time_zone: string | null;
5668
+ slots: MarketingPostScheduleSlot[];
5669
+ next_slot: string | null;
5670
+ }
5671
+ /** A weekday and hour an account's published posts drew the most interactions at. */
5672
+ export interface MarketingBestTime {
5673
+ weekday: number;
5674
+ hour: number;
5675
+ posts: number;
5676
+ average_interactions: number;
5677
+ }
5678
+ /** The best times to post, best first, with how many posts they were read from. */
5679
+ export interface MarketingBestTimes {
5680
+ time_zone: string;
5681
+ sample: number;
5682
+ times: MarketingBestTime[];
5556
5683
  }
5557
5684
  /** Who can view a TikTok video, as TikTok's creator info offers the levels. */
5558
5685
  export type TikTokPrivacyLevel = "PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY";
@@ -7781,12 +7908,68 @@ export interface NemphiClient {
7781
7908
  media_urls?: string[];
7782
7909
  media_type?: MarketingPost["media_type"];
7783
7910
  scheduled_at?: string;
7784
- } & TikTokPostChoices): Promise<{
7911
+ /** Per-account captions keyed by channel id; an account named here gets its own text. */
7912
+ captions?: Record<string, string>;
7913
+ /** Schedule each account's post for its next free posting time instead of scheduled_at. */
7914
+ queue?: boolean;
7915
+ } & TikTokPostChoices & MarketingPostDetailChoices): Promise<{
7785
7916
  batch_id: string;
7786
7917
  posts: MarketingPost[];
7787
7918
  note?: string;
7788
7919
  }>;
7789
7920
  getTikTokCreatorInfo(channelId: string): Promise<TikTokCreatorInfo>;
7921
+ writeMarketingCaptions(input: {
7922
+ brief: string;
7923
+ providers: string[];
7924
+ tone?: "friendly" | "professional" | "playful" | "bold";
7925
+ language?: string;
7926
+ current_caption?: string;
7927
+ }): Promise<MarketingCaptionDraft>;
7928
+ getMarketingCaptionDraft(draftId: string): Promise<MarketingCaptionDraft>;
7929
+ generateMarketingImage(input: {
7930
+ prompt: string;
7931
+ orientation?: "square" | "portrait" | "landscape";
7932
+ }): Promise<MarketingGeneration>;
7933
+ listMarketingGenerations(input?: {
7934
+ kind?: "image" | "video";
7935
+ status?: MarketingGeneration["status"];
7936
+ }): Promise<MarketingGeneration[]>;
7937
+ listMarketingPostSchedules(): Promise<MarketingPostSchedule[]>;
7938
+ setMarketingPostSchedule(input: {
7939
+ channel_id: string;
7940
+ time_zone: string;
7941
+ slots: MarketingPostScheduleSlot[];
7942
+ }): Promise<MarketingPostSchedule>;
7943
+ getMarketingBestPostTimes(input: {
7944
+ channel_id: string;
7945
+ time_zone?: string;
7946
+ }): Promise<MarketingBestTimes>;
7947
+ setMarketingPostTags(input: {
7948
+ post_id: string;
7949
+ tags: string[];
7950
+ }): Promise<MarketingPost>;
7951
+ listMarketingPostNotes(postId: string): Promise<MarketingPostNote[]>;
7952
+ addMarketingPostNote(input: {
7953
+ post_id: string;
7954
+ body: string;
7955
+ }): Promise<MarketingPostNote>;
7956
+ listMarketingSnippets(input?: {
7957
+ kind?: MarketingSnippet["kind"];
7958
+ }): Promise<MarketingSnippet[]>;
7959
+ saveMarketingSnippet(input: {
7960
+ id?: string;
7961
+ kind: MarketingSnippet["kind"];
7962
+ name: string;
7963
+ body: string;
7964
+ }): Promise<MarketingSnippet>;
7965
+ deleteMarketingSnippet(id: string): Promise<MarketingSnippet>;
7966
+ listMarketingIdeas(): Promise<MarketingIdea[]>;
7967
+ saveMarketingIdea(input: {
7968
+ id?: string;
7969
+ title: string;
7970
+ notes?: string;
7971
+ }): Promise<MarketingIdea>;
7972
+ deleteMarketingIdea(id: string): Promise<MarketingIdea>;
7790
7973
  listMarketingPostRevisions(input: {
7791
7974
  post_id: string;
7792
7975
  before_version?: number;
@@ -7814,7 +7997,7 @@ export interface NemphiClient {
7814
7997
  caption?: string;
7815
7998
  media_type?: MarketingPost["media_type"];
7816
7999
  media_urls?: string[];
7817
- } & TikTokPostChoices): Promise<{
8000
+ } & TikTokPostChoices & MarketingPostDetailChoices): Promise<{
7818
8001
  post: MarketingPost;
7819
8002
  }>;
7820
8003
  submitMarketingPost(postId: string): Promise<{
@@ -7895,6 +8078,28 @@ export interface NemphiClient {
7895
8078
  conversation_id: string;
7896
8079
  body: string;
7897
8080
  }): Promise<MarketingMessage>;
8081
+ listMarketingComments(input?: {
8082
+ channel_id?: string;
8083
+ post_id?: string;
8084
+ limit?: number;
8085
+ }): Promise<MarketingComment[]>;
8086
+ replyToMarketingComment(input: {
8087
+ comment_id: string;
8088
+ body: string;
8089
+ }): Promise<MarketingComment>;
8090
+ hideMarketingComment(input: {
8091
+ comment_id: string;
8092
+ hidden: boolean;
8093
+ }): Promise<MarketingComment>;
8094
+ assignMarketingConversation(input: {
8095
+ conversation_id: string;
8096
+ assignee_user_id?: string;
8097
+ }): Promise<MarketingConversation>;
8098
+ listMarketingConversationNotes(conversationId: string): Promise<MarketingConversationNote[]>;
8099
+ addMarketingConversationNote(input: {
8100
+ conversation_id: string;
8101
+ body: string;
8102
+ }): Promise<MarketingConversationNote>;
7898
8103
  linkMarketingConversationParty(input: {
7899
8104
  conversation_id: string;
7900
8105
  party_id: string;
@@ -8694,22 +8899,48 @@ export interface NemphiClient {
8694
8899
  next_before?: number;
8695
8900
  }>;
8696
8901
  /**
8697
- * Live tail of the action ledger (`GET /v1/events/stream`, SSE).
8698
- * Resumes from `cursor` (last seen action id); abort via `signal`.
8902
+ * One connection to the workspace's realtime stream
8903
+ * (`GET /v1/events/stream`, server-sent events): every frame it carries,
8904
+ * checked by its `type`, until the connection ends (the server closes a
8905
+ * stream after 15 minutes) or `signal` aborts. `action` and
8906
+ * `notification` are wake-ups naming a row; read the row back. The
8907
+ * stream keeps no position, so a reader that connects again re-reads
8908
+ * what it shows. `openRealtimeSocket` reconnects for you.
8699
8909
  */
8700
8910
  streamEvents(opts?: {
8911
+ /** @deprecated Ignored: the stream keeps no position. */
8701
8912
  cursor?: number;
8702
8913
  signal?: AbortSignal;
8703
- }): AsyncGenerator<Action, void, void>;
8914
+ }): AsyncGenerator<RealtimeEvent, void, void>;
8704
8915
  /**
8705
- * The workspace's realtime events, polled from `GET /v1/events/poll`
8706
- * every two seconds (at once while the server has more), with retries
8707
- * until `close()`: the ledger and the caller's notifications as
8708
- * wake-ups, the workspace's frames as they are, and who is online when
8709
- * that changed. Each poll keeps the caller online. The web app polls the
8710
- * same route through its own server route.
8916
+ * The workspace's realtime events from `GET /v1/events/stream`, opened
8917
+ * again with backoff whenever it drops, until `close()`: the ledger and
8918
+ * the caller's notifications as wake-ups, the workspace's frames as they
8919
+ * are, and who is online. The connection keeps the caller online.
8711
8920
  */
8712
8921
  openRealtimeSocket(options: RealtimeSocketOptions): RealtimeSocket;
8922
+ /**
8923
+ * One chat thread's own stream (`GET /v1/threads/{id}/stream`), for a
8924
+ * member who sits in it: the answers its agent runs are writing
8925
+ * (`run_delta`) and each run step's end (`run`). It opens the stream
8926
+ * again with backoff whenever it drops or the server ends it, until
8927
+ * `signal` aborts; a refusal that will not change (401, 403, the thread
8928
+ * not found as 404) throws an `ApiError`.
8929
+ *
8930
+ * Every connection first replays the turn being written, so a reader
8931
+ * that reconnects mid-answer has all of it. Fold the pieces by
8932
+ * `(seq, n)`: a later `seq` starts the run's text over, a piece already
8933
+ * held (the same `seq`, an `n` at or below the last) changes nothing.
8934
+ * The answer itself always lands as a message; a `run` frame whose
8935
+ * outcome is `continue` or `parked` means the text so far was preamble.
8936
+ * A step that ended while the stream was down is not replayed, so
8937
+ * `onOpen` after the first is the moment to re-read the thread.
8938
+ */
8939
+ streamThread(threadId: string, opts?: {
8940
+ signal?: AbortSignal;
8941
+ /** Called each time the stream answers. */
8942
+ onOpen?: () => void;
8943
+ }): AsyncGenerator<ThreadStreamEvent, void, void>;
8713
8944
  /** Say the caller is writing in a thread or an inbox conversation (`POST /v1/events/typing`); nothing is stored. */
8714
8945
  sendTyping(input: {
8715
8946
  scope: TypingScope;