@oxygen-agent/cli 1.1046.51 → 1.1047.23

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/README.md CHANGED
@@ -34,4 +34,4 @@ oxygen update
34
34
 
35
35
  For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
36
36
 
37
- Version: 1.1046.51
37
+ Version: 1.1047.23
@@ -69,13 +69,15 @@ function buildPublishingPostCreateBody(options) {
69
69
  const status = resolvePublishingCreateStatus(options);
70
70
  const publishAt = readOption(options.publishAt);
71
71
  const groupWith = readOption(options.groupWith);
72
- if (!publishAt && !groupWith) {
72
+ const contentPost = readOption(options.contentPost);
73
+ if (!publishAt && !groupWith && !contentPost) {
73
74
  throw new OxygenError("invalid_request", "Pass --publish-at, or --group-with <post_id> to add a channel to a post that already has a time.", { exitCode: 2 });
74
75
  }
75
76
  const body = {
76
77
  content_text: readPublishingPostText(options, true),
77
78
  ...(publishAt ? { publish_at: publishAt } : {}),
78
79
  ...(groupWith ? { group_with: groupWith } : {}),
80
+ ...(contentPost ? { content_post_id: contentPost } : {}),
79
81
  status,
80
82
  approved: options.approved === true,
81
83
  };
@@ -792,6 +794,40 @@ function buildPublishingBoostBody(postId, options) {
792
794
  ...(commentPool ? { comment_pool: commentPool } : {}),
793
795
  };
794
796
  }
797
+ function buildPublishingContentBody(options, update) {
798
+ const notesFile = readOption(options.notesFile);
799
+ const notes = notesFile ? readPublishingTextFile(notesFile, "--notes-file") : options.notes;
800
+ const plannedAt = readOption(options.plannedAt);
801
+ const body = {
802
+ ...(options.name !== undefined ? { name: options.name } : {}),
803
+ ...(notes !== undefined ? { notes } : {}),
804
+ ...(readOption(options.stage) ? { stage_id: readOption(options.stage) } : {}),
805
+ ...(plannedAt ? { planned_at: plannedAt } : {}),
806
+ ...(options.clearPlannedAt ? { planned_at: null } : {}),
807
+ };
808
+ if (update && Object.keys(body).length === 0) {
809
+ throw new OxygenError("invalid_request", "Pass --name, --notes, --notes-file, --stage, --planned-at or --clear-planned-at.", { exitCode: 2 });
810
+ }
811
+ if (!update && !options.name?.trim() && !(typeof notes === "string" && notes.trim())) {
812
+ throw new OxygenError("invalid_request", "Pass --name or --notes.", { exitCode: 2 });
813
+ }
814
+ return body;
815
+ }
816
+ function buildPublishingStageBody(options, update) {
817
+ const position = options.position === undefined ? undefined : readNonNegativeInt(options.position);
818
+ const body = {
819
+ ...(options.label !== undefined ? { label: options.label } : {}),
820
+ ...(!update && readOption(options.after) ? { after_stage_id: readOption(options.after) } : {}),
821
+ ...(position !== undefined ? { position } : {}),
822
+ };
823
+ if (update && Object.keys(body).length === 0) {
824
+ throw new OxygenError("invalid_request", "Pass --label or --position.", { exitCode: 2 });
825
+ }
826
+ if (!update && !options.label?.trim()) {
827
+ throw new OxygenError("invalid_request", "Pass --label.", { exitCode: 2 });
828
+ }
829
+ return body;
830
+ }
795
831
  function buildPublishingIdeaBody(options) {
796
832
  const topic = readOption(options.topic);
797
833
  const channels = splitCommaList(options.channels);
@@ -845,6 +881,7 @@ export function registerPublishingFamily(program, handleAsyncAction) {
845
881
  .addCommand(new Command("create")
846
882
  .description("Create a personal Publishing post. Use --ugc-participation-id to save it into one program as an unapproved draft; otherwise it defaults to scheduled and publishes only after approval.")
847
883
  .option("--publish-at <iso>", "When the post publishes, e.g. 2026-10-06T09:00:00+02:00. With Z or an offset it is that exact instant; without one (2026-10-06T09:00) it is wall-clock time in --timezone. Required unless --group-with, where the channel takes that post's time.")
884
+ .option("--content-post <post_id>", "Write this channel post for a post on the board (`publishing content list`): the first one keeps the post's name and notes, later ones join it and publish at its time.")
848
885
  .option("--group-with <post_id>", "Add this as another channel of an existing post (one post per channel), with its own account, copy and media; pass the same --media ids to share one upload, or other ones for different files. It publishes at that post's time, so omit --publish-at and --timezone; `publishing posts get` lists the post's channels under group.")
849
886
  .option("--provider <provider>", "Publishing provider: linkedin, x, instagram, tiktok, facebook, or youtube. Defaults to linkedin. LinkedIn publishes through --sender; every other provider publishes through a connected account (--provider-connection), which the worker needs before it can deliver.")
850
887
  .option("--channel <channel>", "Publishing channel override. Defaults to provider.")
@@ -1528,6 +1565,105 @@ export function registerPublishingFamily(program, handleAsyncAction) {
1528
1565
  .option("--limit <n>", "Maximum ideas to return.")
1529
1566
  .option("--json", "Print a JSON envelope.")
1530
1567
  .action(async (options) => {
1531
- await handleAsyncAction("publishing ideas list", options, () => requestOxygen(buildPublishingDraftsListPath({ ...options, kind: "idea" })));
1568
+ await handleAsyncAction("publishing ideas list", options, () => {
1569
+ const limit = readOption(options.limit);
1570
+ return requestOxygen(`/api/cli/publishing/content?without_channels=true${limit ? `&limit=${encodeURIComponent(limit)}` : ""}`);
1571
+ });
1572
+ })))
1573
+ .addCommand(new Command("content")
1574
+ .description("Posts as whole pieces of content on the board: name, stage, notes and planned date, with or without channel posts yet.")
1575
+ .addCommand(new Command("list")
1576
+ .description("List posts on the board with their stage, notes and channel posts, newest first.")
1577
+ .option("--without-channels", "Only posts with no channel post yet (ideas and notes-only posts).")
1578
+ .option("--limit <n>", "Maximum posts to return.")
1579
+ .option("--json", "Print a JSON envelope.")
1580
+ .action(async (options) => {
1581
+ await handleAsyncAction("publishing content list", options, () => {
1582
+ const params = new URLSearchParams();
1583
+ if (options.withoutChannels)
1584
+ params.set("without_channels", "true");
1585
+ const limit = readOption(options.limit);
1586
+ if (limit)
1587
+ params.set("limit", limit);
1588
+ const query = params.toString();
1589
+ return requestOxygen(`/api/cli/publishing/content${query ? `?${query}` : ""}`);
1590
+ });
1591
+ }))
1592
+ .addCommand(new Command("get")
1593
+ .description("Read one post: its stage, notes, planned date and channel posts. Takes a post id or any of its channel post ids.")
1594
+ .argument("<post_id>", "Post id.")
1595
+ .option("--json", "Print a JSON envelope.")
1596
+ .action(async (postId, options) => {
1597
+ await handleAsyncAction("publishing content get", options, () => requestOxygen(`/api/cli/publishing/content/${encodeURIComponent(postId)}`));
1598
+ }))
1599
+ .addCommand(new Command("create")
1600
+ .description("Put a post on the board with no channel post yet: an idea, or notes to write from later. Free; nothing is scheduled.")
1601
+ .option("--name <name>", "The post's name on the board.")
1602
+ .option("--notes <text>", "Notes: brief, research, outline. Never published.")
1603
+ .option("--notes-file <path>", "Read the notes from a local file.")
1604
+ .option("--stage <stage_id>", "A planning stage (`publishing stages list`); default the first one.")
1605
+ .option("--planned-at <iso>", "When it is planned to go out (for the calendar); scheduling happens per channel post.")
1606
+ .option("--json", "Print a JSON envelope.")
1607
+ .action(async (options) => {
1608
+ await handleAsyncAction("publishing content create", options, () => requestOxygen("/api/cli/publishing/content", { method: "POST", body: buildPublishingContentBody(options, false) }));
1609
+ }))
1610
+ .addCommand(new Command("update")
1611
+ .description("Change a post's name, notes, planned date or planning stage. A name also renames every channel post. Review, Scheduled, Published and Cancelled follow approval and publishing.")
1612
+ .argument("<post_id>", "Post id, or any of its channel post ids.")
1613
+ .option("--name <name>", "New name; an empty string clears it.")
1614
+ .option("--notes <text>", "Replace the notes; an empty string clears them.")
1615
+ .option("--notes-file <path>", "Replace the notes from a local file.")
1616
+ .option("--stage <stage_id>", "Move to this planning stage.")
1617
+ .option("--planned-at <iso>", "New planned date.")
1618
+ .option("--clear-planned-at", "Remove the planned date.")
1619
+ .option("--json", "Print a JSON envelope.")
1620
+ .action(async (postId, options) => {
1621
+ await handleAsyncAction("publishing content update", options, () => requestOxygen(`/api/cli/publishing/content/${encodeURIComponent(postId)}`, { method: "PATCH", body: buildPublishingContentBody(options, true) }));
1622
+ }))
1623
+ .addCommand(new Command("delete")
1624
+ .description("Delete a post that has no channel post left (delete its channel posts first with `publishing posts delete`).")
1625
+ .argument("<post_id>", "Post id.")
1626
+ .option("--json", "Print a JSON envelope.")
1627
+ .action(async (postId, options) => {
1628
+ await handleAsyncAction("publishing content delete", options, () => requestOxygen(`/api/cli/publishing/content/${encodeURIComponent(postId)}`, { method: "DELETE" }));
1629
+ })))
1630
+ .addCommand(new Command("stages")
1631
+ .description("The board's stages: rename, add, reorder and remove planning stages; Review, Scheduled, Published and Cancelled can be renamed.")
1632
+ .addCommand(new Command("list")
1633
+ .description("List the board's stages in order.")
1634
+ .option("--json", "Print a JSON envelope.")
1635
+ .action(async (options) => {
1636
+ await handleAsyncAction("publishing stages list", options, () => requestOxygen("/api/cli/publishing/stages"));
1637
+ }))
1638
+ .addCommand(new Command("create")
1639
+ .description("Add a planning stage to the board.")
1640
+ .option("--label <label>", "The stage's name.")
1641
+ .option("--after <stage_id>", "Place it after this planning stage; default after the last one.")
1642
+ .option("--json", "Print a JSON envelope.")
1643
+ .action(async (options) => {
1644
+ await handleAsyncAction("publishing stages create", options, () => requestOxygen("/api/cli/publishing/stages", { method: "POST", body: buildPublishingStageBody(options, false) }));
1645
+ }))
1646
+ .addCommand(new Command("update")
1647
+ .description("Rename a stage, or move a planning stage to another place among the planning stages.")
1648
+ .argument("<stage_id>", "Stage id.")
1649
+ .option("--label <label>", "New name.")
1650
+ .option("--position <n>", "New place among the planning stages, 0 first.")
1651
+ .option("--json", "Print a JSON envelope.")
1652
+ .action(async (stageId, options) => {
1653
+ await handleAsyncAction("publishing stages update", options, () => requestOxygen(`/api/cli/publishing/stages/${encodeURIComponent(stageId)}`, { method: "PATCH", body: buildPublishingStageBody(options, true) }));
1654
+ }))
1655
+ .addCommand(new Command("delete")
1656
+ .description("Remove a planning stage; its posts move to --move-to or the stage before it.")
1657
+ .argument("<stage_id>", "Stage id.")
1658
+ .option("--move-to <stage_id>", "Planning stage that takes its posts.")
1659
+ .option("--json", "Print a JSON envelope.")
1660
+ .action(async (stageId, options) => {
1661
+ await handleAsyncAction("publishing stages delete", options, () => {
1662
+ const moveTo = readOption(options.moveTo);
1663
+ return requestOxygen(`/api/cli/publishing/stages/${encodeURIComponent(stageId)}`, {
1664
+ method: "DELETE",
1665
+ ...(moveTo ? { body: { move_to_stage_id: moveTo } } : {}),
1666
+ });
1667
+ });
1532
1668
  })));
1533
1669
  }
@@ -12,7 +12,9 @@ export declare function placementReportExpired(provider: string, results: unknow
12
12
  * probe was sent: the vendor closed the test without measuring it, so its
13
13
  * "completed" score describes nothing. waiting_for_email rows legitimately
14
14
  * predate the send and never count. Vendor timestamps carry microseconds;
15
- * Date.parse truncates them to milliseconds.
15
+ * Date.parse truncates them to milliseconds. Only a confirmed send time counts:
16
+ * an unconfirmed probe may have left before its uncertain verdict, so that verdict
17
+ * time clocks the report deadline and nothing else.
16
18
  */
17
19
  export declare function placementSeedsClosedBeforeSend(provider: string, currentResults: unknown, pollResults: unknown): boolean;
18
20
  /**
@@ -17,9 +17,10 @@ function seedReceipt(provider, results) {
17
17
  * ended `uncertain` and is never retried), the time that verdict was recorded. The
18
18
  * report then decides whether the probe landed.
19
19
  */
20
- function seedSendMs(provider, results) {
20
+ function seedSendMs(provider, results, { confirmedOnly = false } = {}) {
21
21
  const send = seedReceipt(provider, results);
22
- const at = send?.status === "sent" ? send.sent_at : send?.status === "uncertain" ? send.uncertain_at : null;
22
+ const at = send?.status === "sent" ? send.sent_at
23
+ : send?.status === "uncertain" && !confirmedOnly ? send.uncertain_at : null;
23
24
  if (typeof at !== "string")
24
25
  return null;
25
26
  const sent = Date.parse(at);
@@ -41,10 +42,12 @@ const NOT_RECEIVED_FOLDERS = new Set(["missing", "not_received", "not_found"]);
41
42
  * probe was sent: the vendor closed the test without measuring it, so its
42
43
  * "completed" score describes nothing. waiting_for_email rows legitimately
43
44
  * predate the send and never count. Vendor timestamps carry microseconds;
44
- * Date.parse truncates them to milliseconds.
45
+ * Date.parse truncates them to milliseconds. Only a confirmed send time counts:
46
+ * an unconfirmed probe may have left before its uncertain verdict, so that verdict
47
+ * time clocks the report deadline and nothing else.
45
48
  */
46
49
  export function placementSeedsClosedBeforeSend(provider, currentResults, pollResults) {
47
- const sent = seedSendMs(provider, currentResults);
50
+ const sent = seedSendMs(provider, currentResults, { confirmedOnly: true });
48
51
  if (sent === null || !pollResults || typeof pollResults !== "object")
49
52
  return false;
50
53
  const emails = pollResults.emails;
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The content board's stages (docs/product/posts.md, 2026-11-18): pure and
3
+ * browser-safe, so the store, the routes and the board resolve a post's stage
4
+ * the same way.
5
+ *
6
+ * Planning stages belong to the workspace: renamed, added, reordered, removed.
7
+ * One stage of each publishing kind (review, scheduled, published, canceled) is
8
+ * renamable but never removed, and only approval and dispatch move a post into
9
+ * it: a post's channel posts decide those, never a stored choice.
10
+ */
11
+ export declare const CONTENT_STAGE_KINDS: readonly ["planning", "review", "scheduled", "published", "canceled"];
12
+ export type ContentStageKind = typeof CONTENT_STAGE_KINDS[number];
13
+ export type ContentSystemStageKind = Exclude<ContentStageKind, "planning">;
14
+ /** The publishing kinds, in board order after every planning stage. */
15
+ export declare const CONTENT_SYSTEM_STAGE_KINDS: readonly ContentSystemStageKind[];
16
+ export type ContentStage = {
17
+ id: string;
18
+ kind: ContentStageKind;
19
+ label: string;
20
+ position: number;
21
+ };
22
+ /** What a new workspace starts with. */
23
+ export declare const DEFAULT_CONTENT_STAGES: ReadonlyArray<{
24
+ kind: ContentStageKind;
25
+ label: string;
26
+ }>;
27
+ export declare const CONTENT_STAGE_LABEL_MAX = 60;
28
+ /**
29
+ * Where a post's channel posts stand, as the Posts views already fold them
30
+ * (`postEntryStatus` in the web app): `null` when the post has no channel post.
31
+ */
32
+ export type ContentChannelPhase = "draft" | "waiting_on_approval" | "scheduled" | "published" | "canceled" | null;
33
+ export declare function isContentStageKind(value: unknown): value is ContentStageKind;
34
+ /** Board order: planning stages by position, then the publishing stages in their fixed order. */
35
+ export declare function orderContentStages<T extends ContentStage>(stages: readonly T[]): T[];
36
+ /**
37
+ * The stage a post shows in. Its channel posts decide once any of them is in
38
+ * review, scheduled, published or cancelled; until then it is the stored
39
+ * planning stage, or, when none is stored (or it was removed), the first
40
+ * planning stage for a post with no channel post and the last one for a post
41
+ * already being written.
42
+ */
43
+ export declare function resolveContentStage<T extends ContentStage>(stages: readonly T[], storedStageId: string | null | undefined, phase: ContentChannelPhase): T | null;
44
+ /** One channel post's stored state, as `contentChannelPhase` reads it. */
45
+ export type ContentChannelState = {
46
+ status: string;
47
+ approvalStatus: string;
48
+ };
49
+ /**
50
+ * A post's phase across its channel posts, folded as the Posts views fold them:
51
+ * review when any channel needs a person, cancelled only when every channel was,
52
+ * otherwise the least advanced live channel. `null` for a post with no channel post.
53
+ */
54
+ export declare function contentChannelPhase(channels: readonly ContentChannelState[]): ContentChannelPhase;
@@ -0,0 +1,89 @@
1
+ /**
2
+ * The content board's stages (docs/product/posts.md, 2026-11-18): pure and
3
+ * browser-safe, so the store, the routes and the board resolve a post's stage
4
+ * the same way.
5
+ *
6
+ * Planning stages belong to the workspace: renamed, added, reordered, removed.
7
+ * One stage of each publishing kind (review, scheduled, published, canceled) is
8
+ * renamable but never removed, and only approval and dispatch move a post into
9
+ * it: a post's channel posts decide those, never a stored choice.
10
+ */
11
+ export const CONTENT_STAGE_KINDS = ["planning", "review", "scheduled", "published", "canceled"];
12
+ /** The publishing kinds, in board order after every planning stage. */
13
+ export const CONTENT_SYSTEM_STAGE_KINDS = ["review", "scheduled", "published", "canceled"];
14
+ /** What a new workspace starts with. */
15
+ export const DEFAULT_CONTENT_STAGES = [
16
+ { kind: "planning", label: "Idea" },
17
+ { kind: "planning", label: "Drafting" },
18
+ { kind: "review", label: "Review" },
19
+ { kind: "scheduled", label: "Scheduled" },
20
+ { kind: "published", label: "Published" },
21
+ { kind: "canceled", label: "Cancelled" },
22
+ ];
23
+ export const CONTENT_STAGE_LABEL_MAX = 60;
24
+ const PHASE_KIND = {
25
+ waiting_on_approval: "review",
26
+ scheduled: "scheduled",
27
+ published: "published",
28
+ canceled: "canceled",
29
+ };
30
+ export function isContentStageKind(value) {
31
+ return typeof value === "string" && CONTENT_STAGE_KINDS.includes(value);
32
+ }
33
+ /** Board order: planning stages by position, then the publishing stages in their fixed order. */
34
+ export function orderContentStages(stages) {
35
+ const planning = stages
36
+ .filter((stage) => stage.kind === "planning")
37
+ .sort((a, b) => a.position - b.position || a.id.localeCompare(b.id));
38
+ const system = CONTENT_SYSTEM_STAGE_KINDS
39
+ .map((kind) => stages.find((stage) => stage.kind === kind))
40
+ .filter((stage) => Boolean(stage));
41
+ return [...planning, ...system];
42
+ }
43
+ /**
44
+ * The stage a post shows in. Its channel posts decide once any of them is in
45
+ * review, scheduled, published or cancelled; until then it is the stored
46
+ * planning stage, or, when none is stored (or it was removed), the first
47
+ * planning stage for a post with no channel post and the last one for a post
48
+ * already being written.
49
+ */
50
+ export function resolveContentStage(stages, storedStageId, phase) {
51
+ const ordered = orderContentStages(stages);
52
+ if (phase && phase !== "draft") {
53
+ return ordered.find((stage) => stage.kind === PHASE_KIND[phase]) ?? null;
54
+ }
55
+ const planning = ordered.filter((stage) => stage.kind === "planning");
56
+ const stored = storedStageId ? planning.find((stage) => stage.id === storedStageId) : undefined;
57
+ if (stored)
58
+ return stored;
59
+ return (phase === null ? planning[0] : planning[planning.length - 1]) ?? null;
60
+ }
61
+ function channelPhase(channel) {
62
+ if (channel.status === "canceled" || channel.status === "published")
63
+ return channel.status;
64
+ if (channel.status === "failed" || channel.approvalStatus === "needs_approval")
65
+ return "waiting_on_approval";
66
+ if (channel.status === "queued" || channel.status === "publishing" || channel.status === "scheduled")
67
+ return "scheduled";
68
+ return "draft";
69
+ }
70
+ /**
71
+ * A post's phase across its channel posts, folded as the Posts views fold them:
72
+ * review when any channel needs a person, cancelled only when every channel was,
73
+ * otherwise the least advanced live channel. `null` for a post with no channel post.
74
+ */
75
+ export function contentChannelPhase(channels) {
76
+ if (channels.length === 0)
77
+ return null;
78
+ const phases = channels.map(channelPhase);
79
+ if (phases.includes("waiting_on_approval"))
80
+ return "waiting_on_approval";
81
+ const live = phases.filter((phase) => phase !== "canceled");
82
+ if (live.length === 0)
83
+ return "canceled";
84
+ for (const phase of ["draft", "scheduled", "published"]) {
85
+ if (live.includes(phase))
86
+ return phase;
87
+ }
88
+ return live[0] ?? null;
89
+ }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * A LinkedIn account whose invitations or InMails LinkedIn refuses as the
3
+ * ACCOUNT's restriction, with the provider proving nothing was sent. Dispatch
4
+ * parks that account's invitations (or InMails) and keeps every lead waiting
5
+ * instead of failing it (`senderWriteRestrictionScope`); this record is how the
6
+ * account, its Sequences and the workspace learn that it happened.
7
+ *
8
+ * Plain T-478: an account past LinkedIn's allowance for invitations with a note
9
+ * held 149 leads of two Sequences for 13 days while it read `active` with health
10
+ * `low`, and every waiting lead said "LinkedIn asked the sender to slow down".
11
+ *
12
+ * Stored on `ox_sequencer.sender_accounts.metadata`, keyed by the parked provider
13
+ * operation (`users_invite`, `inmail`). Written by dispatch on each refusal and
14
+ * removed by the next send of that kind from the account. Browser-safe.
15
+ */
16
+ export declare const LINKEDIN_SEND_RESTRICTIONS_METADATA_KEY = "send_restrictions";
17
+ /**
18
+ * When OXYGEN last emailed the workspace about any restriction of this account.
19
+ * Survives the record itself, so an account that flaps between refused and
20
+ * accepted is not announced more than once per LINKEDIN_SEND_RESTRICTION_ALERT_INTERVAL_MS.
21
+ */
22
+ export declare const LINKEDIN_SEND_RESTRICTION_ALERTED_AT_METADATA_KEY = "send_restriction_alerted_at";
23
+ /** One workspace email per account per week at most, however often the restriction returns. */
24
+ export declare const LINKEDIN_SEND_RESTRICTION_ALERT_INTERVAL_MS: number;
25
+ /**
26
+ * A restriction nothing refused for this long is history, not a hold: while
27
+ * leads wait, dispatch asks LinkedIn at least daily (the cooldown backs off to a
28
+ * day) and moves `last_refused_at`. Readers stop showing it, and the next refusal
29
+ * starts a new restriction (`recordLinkedInSendRestriction`).
30
+ */
31
+ export declare const LINKEDIN_SEND_RESTRICTION_STALE_MS: number;
32
+ /**
33
+ * What LinkedIn refused:
34
+ * - `invite_note_allowance`: "You have reached the limit for custom messages" —
35
+ * the account has used its allowance of invitations with a note.
36
+ * - `account_restricted`: an access restriction LinkedIn did not explain.
37
+ */
38
+ export type LinkedInSendRestrictionRefusal = "invite_note_allowance" | "account_restricted";
39
+ export type LinkedInSendRestrictionKind = "invite" | "inmail";
40
+ export type LinkedInSendRestriction = {
41
+ /** The parked provider operation (`users_invite`, `inmail`). */
42
+ operation: string;
43
+ actionKind: LinkedInSendRestrictionKind;
44
+ refusal: LinkedInSendRestrictionRefusal;
45
+ /** LinkedIn's own sentence as the provider relayed it, when it gave one. */
46
+ providerMessage: string | null;
47
+ firstRefusedAt: string;
48
+ lastRefusedAt: string;
49
+ /** When dispatch asks LinkedIn again: the parked operation's cooldown. */
50
+ retryAt: string | null;
51
+ /** When the workspace was emailed about this restriction; null until then. */
52
+ alertedAt: string | null;
53
+ };
54
+ /**
55
+ * The account's current restrictions, newest refusal first: not those nothing
56
+ * refused within LINKEDIN_SEND_RESTRICTION_STALE_MS of `now`. Pure and total.
57
+ */
58
+ export declare function readLinkedInSendRestrictions(metadata: Record<string, unknown> | null | undefined, now?: Date): LinkedInSendRestriction[];
59
+ /** The restriction parking this provider operation, if the account has one. */
60
+ export declare function linkedInSendRestrictionFor(metadata: Record<string, unknown> | null | undefined, operation: string, now?: Date): LinkedInSendRestriction | null;
61
+ /**
62
+ * What the account's waiting leads can be moved by: shared by the account's
63
+ * explanation and the workspace email, so both name the same actions.
64
+ */
65
+ export declare function linkedInSendRestrictionRemedy(restriction: Pick<LinkedInSendRestriction, "actionKind" | "refusal">): string;
66
+ /**
67
+ * The account-level explanation (senders health, the Connections notice and
68
+ * panel): what LinkedIn refuses, that every send of that kind from the account
69
+ * waits unsent, and what moves the leads. Never names the provider.
70
+ */
71
+ export declare function linkedInSendRestrictionExplanation(input: {
72
+ displayName: string | null;
73
+ restriction: Pick<LinkedInSendRestriction, "actionKind" | "refusal">;
74
+ }): string;
@@ -0,0 +1,102 @@
1
+ /**
2
+ * A LinkedIn account whose invitations or InMails LinkedIn refuses as the
3
+ * ACCOUNT's restriction, with the provider proving nothing was sent. Dispatch
4
+ * parks that account's invitations (or InMails) and keeps every lead waiting
5
+ * instead of failing it (`senderWriteRestrictionScope`); this record is how the
6
+ * account, its Sequences and the workspace learn that it happened.
7
+ *
8
+ * Plain T-478: an account past LinkedIn's allowance for invitations with a note
9
+ * held 149 leads of two Sequences for 13 days while it read `active` with health
10
+ * `low`, and every waiting lead said "LinkedIn asked the sender to slow down".
11
+ *
12
+ * Stored on `ox_sequencer.sender_accounts.metadata`, keyed by the parked provider
13
+ * operation (`users_invite`, `inmail`). Written by dispatch on each refusal and
14
+ * removed by the next send of that kind from the account. Browser-safe.
15
+ */
16
+ export const LINKEDIN_SEND_RESTRICTIONS_METADATA_KEY = "send_restrictions";
17
+ /**
18
+ * When OXYGEN last emailed the workspace about any restriction of this account.
19
+ * Survives the record itself, so an account that flaps between refused and
20
+ * accepted is not announced more than once per LINKEDIN_SEND_RESTRICTION_ALERT_INTERVAL_MS.
21
+ */
22
+ export const LINKEDIN_SEND_RESTRICTION_ALERTED_AT_METADATA_KEY = "send_restriction_alerted_at";
23
+ /** One workspace email per account per week at most, however often the restriction returns. */
24
+ export const LINKEDIN_SEND_RESTRICTION_ALERT_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
25
+ /**
26
+ * A restriction nothing refused for this long is history, not a hold: while
27
+ * leads wait, dispatch asks LinkedIn at least daily (the cooldown backs off to a
28
+ * day) and moves `last_refused_at`. Readers stop showing it, and the next refusal
29
+ * starts a new restriction (`recordLinkedInSendRestriction`).
30
+ */
31
+ export const LINKEDIN_SEND_RESTRICTION_STALE_MS = 14 * 24 * 60 * 60 * 1000;
32
+ function isRecord(value) {
33
+ return typeof value === "object" && value !== null && !Array.isArray(value);
34
+ }
35
+ function readText(record, key) {
36
+ const value = record[key];
37
+ return typeof value === "string" && value.trim() ? value.trim() : null;
38
+ }
39
+ /**
40
+ * The account's current restrictions, newest refusal first: not those nothing
41
+ * refused within LINKEDIN_SEND_RESTRICTION_STALE_MS of `now`. Pure and total.
42
+ */
43
+ export function readLinkedInSendRestrictions(metadata, now = new Date()) {
44
+ const stored = metadata?.[LINKEDIN_SEND_RESTRICTIONS_METADATA_KEY];
45
+ if (!isRecord(stored))
46
+ return [];
47
+ const restrictions = [];
48
+ for (const [operation, raw] of Object.entries(stored)) {
49
+ if (!isRecord(raw))
50
+ continue;
51
+ const firstRefusedAt = readText(raw, "first_refused_at");
52
+ const lastRefusedAt = readText(raw, "last_refused_at") ?? firstRefusedAt;
53
+ if (!firstRefusedAt || !lastRefusedAt)
54
+ continue;
55
+ const lastRefused = Date.parse(lastRefusedAt);
56
+ if (!Number.isFinite(lastRefused) || lastRefused < now.getTime() - LINKEDIN_SEND_RESTRICTION_STALE_MS)
57
+ continue;
58
+ restrictions.push({
59
+ operation,
60
+ actionKind: raw.action_kind === "inmail" ? "inmail" : "invite",
61
+ refusal: raw.refusal === "invite_note_allowance" ? "invite_note_allowance" : "account_restricted",
62
+ providerMessage: readText(raw, "provider_message"),
63
+ firstRefusedAt,
64
+ lastRefusedAt,
65
+ retryAt: readText(raw, "retry_at"),
66
+ alertedAt: readText(raw, "alerted_at"),
67
+ });
68
+ }
69
+ return restrictions.sort((a, b) => b.lastRefusedAt.localeCompare(a.lastRefusedAt));
70
+ }
71
+ /** The restriction parking this provider operation, if the account has one. */
72
+ export function linkedInSendRestrictionFor(metadata, operation, now = new Date()) {
73
+ return readLinkedInSendRestrictions(metadata, now).find((restriction) => restriction.operation === operation) ?? null;
74
+ }
75
+ /**
76
+ * What the account's waiting leads can be moved by: shared by the account's
77
+ * explanation and the workspace email, so both name the same actions.
78
+ */
79
+ export function linkedInSendRestrictionRemedy(restriction) {
80
+ if (restriction.actionKind === "invite" && restriction.refusal === "invite_note_allowance") {
81
+ return "To keep them moving, remove the note from the invitation step (invitations without a note have their own, larger LinkedIn limit), or pause the sequences.";
82
+ }
83
+ return "Check the account on LinkedIn, or pause the sequences.";
84
+ }
85
+ /**
86
+ * The account-level explanation (senders health, the Connections notice and
87
+ * panel): what LinkedIn refuses, that every send of that kind from the account
88
+ * waits unsent, and what moves the leads. Never names the provider.
89
+ */
90
+ export function linkedInSendRestrictionExplanation(input) {
91
+ const account = input.displayName?.trim() || "this LinkedIn account";
92
+ const { restriction } = input;
93
+ const inMail = restriction.actionKind === "inmail";
94
+ const allowance = !inMail && restriction.refusal === "invite_note_allowance";
95
+ const refused = inMail
96
+ ? `LinkedIn refuses InMails from ${account}.`
97
+ : allowance
98
+ ? `LinkedIn refuses invitations with a note from ${account}: the account has used LinkedIn's allowance of invitations with a note (accounts without a paid LinkedIn plan get about five a month).`
99
+ : `LinkedIn refuses invitations from ${account}.`;
100
+ const kind = inMail ? "InMail" : "invitation";
101
+ return `${refused} Until LinkedIn accepts one again, every ${kind} from this account waits and nothing is sent to its leads; OXYGEN asks LinkedIn again on its own, backing off to once a day. ${linkedInSendRestrictionRemedy(restriction)}`;
102
+ }
@@ -1,3 +1,3 @@
1
1
  export declare const OXYGEN_VERSION: string;
2
- export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.1014.1219";
2
+ export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.1014.1341";
3
3
  export declare const GEO_EXPORT_MINIMUM_CLI_VERSION = "1.1013.0";
@@ -1 +1 @@
1
- export declare const OXYGEN_BUILD_VERSION = "1.1046.51";
1
+ export declare const OXYGEN_BUILD_VERSION = "1.1047.23";
@@ -1,2 +1,2 @@
1
1
  // GENERATED by scripts/ci/version-stamp.mjs from VERSION + git history. Do not edit; do not commit.
2
- export const OXYGEN_BUILD_VERSION = "1.1046.51";
2
+ export const OXYGEN_BUILD_VERSION = "1.1047.23";
@@ -49,7 +49,7 @@ export const OXYGEN_VERSION = OXYGEN_BUILD_VERSION;
49
49
  // Since 2026-09-28 the release-preparation step advances this literal to the
50
50
  // highest CLI version published on npm for at least 30 days. It never lowers
51
51
  // the floor. The source change lands on dev before the next production release.
52
- export const OXYGEN_MINIMUM_CLI_VERSION = "1.1014.1219";
52
+ export const OXYGEN_MINIMUM_CLI_VERSION = "1.1014.1341";
53
53
  // The internal GEO export first gains required pagination in this dev version.
54
54
  // Earlier pilot clients would save a partial file without its continuation.
55
55
  export const GEO_EXPORT_MINIMUM_CLI_VERSION = "1.1013.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oxygen-agent/cli",
3
- "version": "1.1046.51",
3
+ "version": "1.1047.23",
4
4
  "private": false,
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",