@hraness/ghostget 0.17.2

package/src/provider-contract-input-gmail.ts

@@ -0,0 +1,176 @@
+import type { OperationInput } from "./model";
+import type { ProviderPluginOperationName } from "./provider-plugin-identifiers";
+
+function hasUnsafeControl(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (
+      code <= 0x1f
+      || code === 0x7f
+      || (code >= 0x80 && code <= 0x9f)
+      || code === 0x061c
+      || code === 0x200e
+      || code === 0x200f
+      || (code >= 0x2028 && code <= 0x202e)
+      || (code >= 0x2066 && code <= 0x2069)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isWellFormedText(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return false;
+      index += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) return false;
+  }
+  return true;
+}
+
+function boundedTextIssue(
+  name: string,
+  value: unknown,
+  maximum: number,
+): string | null {
+  if (typeof value !== "string") return null;
+  return value.length < 1
+      || value.length > maximum
+      || !isWellFormedText(value)
+      || hasUnsafeControl(value)
+    ? `input.${name} must be a 1-${maximum} character string without unsafe controls`
+    : null;
+}
+
+function safeIntegerIssue(name: string, value: unknown): string | null {
+  return typeof value === "number" && !Number.isSafeInteger(value)
+    ? `input.${name} must be a safe integer`
+    : null;
+}
+
+export function gmailProviderConditionalInputIssues(
+  action: ProviderPluginOperationName,
+  input: OperationInput,
+  contractVersion = 5,
+): readonly string[] {
+  const issues: string[] = [];
+  const cursorIssue = boundedTextIssue("cursor", input.cursor, 4_096);
+  if (cursorIssue !== null) issues.push(cursorIssue);
+
+  if (action === "contacts.list") {
+    const limitIssue = safeIntegerIssue("limit", input.limit);
+    if (limitIssue !== null) issues.push(limitIssue);
+    if (contractVersion === 4 && input.include_dates !== undefined) {
+      issues.push("input.include_dates is available only in contacts.list contract v5");
+    }
+    if (input.collection === "interactions") {
+      if (contractVersion !== 4 && input.include_dates !== undefined) {
+        issues.push("input.include_dates is not accepted for the interactions collection");
+      }
+      if (input.include_stats !== undefined) {
+        issues.push("input.include_stats is not accepted for the interactions collection");
+      }
+      if (input.stats_scan_limit !== undefined) {
+        issues.push("input.stats_scan_limit is not accepted for the interactions collection");
+      }
+      if (typeof input.before !== "string") {
+        issues.push("input.before is required for the interactions collection");
+      } else {
+        const parsed = new Date(input.before);
+        if (
+          !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.000Z$/u.test(input.before)
+          || !Number.isFinite(parsed.getTime())
+          || parsed.toISOString() !== input.before
+        ) issues.push("input.before must be a canonical whole-second UTC timestamp");
+      }
+      if (input.after !== undefined) {
+        if (typeof input.after !== "string") {
+          issues.push("input.after must be a canonical whole-second UTC timestamp");
+        } else {
+          const parsed = new Date(input.after);
+          if (
+            !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.000Z$/u.test(input.after)
+            || !Number.isFinite(parsed.getTime())
+            || parsed.toISOString() !== input.after
+          ) issues.push("input.after must be a canonical whole-second UTC timestamp");
+        }
+        if (
+          typeof input.before === "string"
+          && typeof input.after === "string"
+          && new Date(input.after).getTime() >= new Date(input.before).getTime()
+        ) issues.push("input.after must precede input.before");
+      }
+    } else {
+      if (input.before !== undefined) {
+        issues.push("input.before is accepted only for the interactions collection");
+      }
+      if (input.after !== undefined) {
+        issues.push("input.after is accepted only for the interactions collection");
+      }
+      const statsScanLimitIssue = safeIntegerIssue("stats_scan_limit", input.stats_scan_limit);
+      if (statsScanLimitIssue !== null) issues.push(statsScanLimitIssue);
+      if (input.include_stats === false && input.stats_scan_limit !== undefined) {
+        issues.push("input.stats_scan_limit is accepted only when include_stats is true");
+      }
+      if (
+        contractVersion !== 4
+        && input.collection === "other-contacts"
+        && input.include_dates === true
+      ) {
+        issues.push("input.include_dates is supported only for saved contacts");
+      }
+      const limit = input.limit ?? 20;
+      const statsScanLimit = input.stats_scan_limit ?? 100;
+      if (
+        input.include_stats !== false
+        &&
+        typeof limit === "number"
+        && Number.isSafeInteger(limit)
+        && limit >= 1
+        && limit <= 100
+        && typeof statsScanLimit === "number"
+        && Number.isSafeInteger(statsScanLimit)
+        && statsScanLimit >= 1
+        && statsScanLimit <= 2_000
+        && limit * statsScanLimit > 2_000
+      ) {
+        issues.push("input.limit multiplied by input.stats_scan_limit must not exceed 2000");
+      }
+    }
+  }
+
+  if (action === "messaging.list") {
+    const limitIssue = safeIntegerIssue("limit", input.limit);
+    if (limitIssue !== null) issues.push(limitIssue);
+    if (input.view === "search") {
+      if (typeof input.query !== "string") {
+        issues.push("input.query is required when view is search");
+      } else {
+        const queryIssue = boundedTextIssue("query", input.query, 512);
+        if (queryIssue !== null) issues.push(queryIssue);
+        else if (input.query.trim().length === 0) {
+          issues.push("input.query must contain a non-whitespace search expression");
+        }
+      }
+    }
+    if (input.view === "inbox" && input.query !== undefined) {
+      issues.push("input.query is not accepted when view is inbox");
+    }
+    if (input.view === "inbox" && input.include_spam_trash !== undefined) {
+      issues.push("input.include_spam_trash is accepted only when view is search");
+    }
+  }
+
+  if (
+    action === "messaging.read"
+    && typeof input.thread_id === "string"
+    && !/^[A-Za-z0-9_-]{1,256}$/u.test(input.thread_id)
+  ) {
+    issues.push("input.thread_id must be an exact bounded Gmail thread ID");
+  }
+  return issues;
+}

package/src/provider-contract-input-linkedin.ts

@@ -0,0 +1,77 @@
+import type { OperationInput } from "./model";
+import type { ProviderPluginOperationName } from "./provider-plugin-identifiers";
+
+export function linkedinProviderConditionalInputIssues(
+  action: ProviderPluginOperationName,
+  input: OperationInput,
+): readonly string[] {
+  const issues: string[] = [];
+  if (action === "contacts.list") {
+    for (const name of ["start", "count"] as const) {
+      if (typeof input[name] === "number" && !Number.isSafeInteger(input[name])) {
+        issues.push(`input.${name} must be a safe integer`);
+      }
+    }
+  }
+  if (action === "posts.read") {
+    if (input.mode === "one") {
+      if (typeof input.post_urn !== "string") {
+        issues.push("input.post_urn is required when mode is one");
+      }
+      if (input.author !== undefined) {
+        issues.push("input.author is not accepted when mode is one");
+      }
+    }
+    if (input.mode === "author") {
+      if (typeof input.author !== "string") {
+        issues.push("input.author is required when mode is author");
+      }
+      if (input.post_urn !== undefined) {
+        issues.push("input.post_urn is not accepted when mode is author");
+      }
+    }
+  }
+  if (action === "posts.publish") {
+    const media = input.media;
+    if (Array.isArray(media) && typeof input.article_url === "string") {
+      issues.push("input.media and input.article_url are mutually exclusive");
+    }
+    if (typeof input.article_url === "string") {
+      try {
+        const url = new URL(input.article_url);
+        if (url.protocol !== "https:" || url.username !== "" || url.password !== "") {
+          issues.push("input.article_url must be a credential-free HTTPS URL");
+        }
+      } catch {
+        issues.push("input.article_url must be a credential-free HTTPS URL");
+      }
+      if (typeof input.article_title !== "string") {
+        issues.push("input.article_title is required with input.article_url");
+      }
+    } else if (
+      input.article_title !== undefined
+      || input.article_description !== undefined
+    ) {
+      issues.push(
+        "input.article_title and input.article_description require input.article_url",
+      );
+    }
+    if (input.alt_text !== undefined && !Array.isArray(media)) {
+      issues.push("input.alt_text requires input.media");
+    }
+    if (input.media_title !== undefined && !Array.isArray(media)) {
+      issues.push("input.media_title requires input.media");
+    }
+  }
+  if (action === "reactions.set") {
+    if (input.enabled === true && typeof input.reaction !== "string") {
+      issues.push("input.reaction is required when input.enabled is true");
+    }
+    if (input.enabled === false && input.reaction !== undefined) {
+      issues.push(
+        "input.reaction is not accepted when input.enabled is false because the operation clears any current reaction",
+      );
+    }
+  }
+  return issues;
+}

package/src/provider-contract-input-x.ts

@@ -0,0 +1,304 @@
+import type { OperationInput } from "./model";
+import type { ProviderPluginOperationName } from "./provider-plugin-identifiers";
+
+function isFileInputValue(value: unknown): boolean {
+  return typeof value === "object"
+    && value !== null
+    && !Array.isArray(value)
+    && (value as { readonly kind?: unknown }).kind === "file"
+    && typeof (value as { readonly reference?: unknown }).reference === "string";
+}
+
+export function xProviderConditionalInputIssues(
+  action: ProviderPluginOperationName,
+  input: OperationInput,
+): readonly string[] {
+  const issues: string[] = [];
+  const xId = (name: string, value: unknown): void => {
+    if (typeof value === "string" && !/^[0-9]{1,19}$/u.test(value)) {
+      issues.push(`input.${name} must be a 1-19 digit X object ID`);
+    }
+  };
+  const xConversationId = (name: string, value: unknown): void => {
+    if (
+      typeof value === "string"
+      && !/^(?:[0-9]{15,19}|[0-9]{1,19}-[0-9]{1,19})$/u.test(value)
+    ) {
+      issues.push(`input.${name} must be an exact legacy X DM conversation ID`);
+    }
+  };
+  if (action === "feeds.read") {
+    const feedLabel = typeof input.feed === "string" ? input.feed : "unknown feed";
+    if (
+      (input.feed === "user" || input.feed === "mentions")
+      && typeof input.user_id !== "string"
+    ) {
+      issues.push("input.user_id is required for user and mentions feeds");
+    }
+    if (input.feed === "list" && typeof input.list_id !== "string") {
+      issues.push("input.list_id is required for the list feed");
+    }
+    if (input.feed === "recent-search" && typeof input.query !== "string") {
+      issues.push("input.query is required for recent-search");
+    }
+    if (
+      input.feed !== "user"
+      && input.feed !== "mentions"
+      && input.user_id !== undefined
+    ) {
+      issues.push("input.user_id is accepted only for user and mentions feeds");
+    }
+    if (input.feed !== "list" && input.list_id !== undefined) {
+      issues.push("input.list_id is accepted only for the list feed");
+    }
+    if (input.feed !== "recent-search" && input.query !== undefined) {
+      issues.push("input.query is accepted only for recent-search");
+    }
+    const supportsTimeAndIdBounds = input.feed === "home-reverse-chronological"
+      || input.feed === "user"
+      || input.feed === "mentions"
+      || input.feed === "recent-search";
+    for (const name of ["since_id", "until_id", "start_time", "end_time"] as const) {
+      if (!supportsTimeAndIdBounds && input[name] !== undefined) {
+        issues.push(`input.${name} is not accepted for ${feedLabel}`);
+      }
+    }
+    if (input.feed !== "home-reverse-chronological" && input.feed !== "user") {
+      if (input.exclude_replies !== undefined) {
+        issues.push(`input.exclude_replies is not accepted for ${feedLabel}`);
+      }
+      if (input.exclude_reposts !== undefined) {
+        issues.push(`input.exclude_reposts is not accepted for ${feedLabel}`);
+      }
+    }
+    if (input.feed !== "recent-search" && input.sort !== undefined) {
+      issues.push("input.sort is accepted only for recent-search");
+    }
+    xId("user_id", input.user_id);
+    xId("list_id", input.list_id);
+    xId("since_id", input.since_id);
+    xId("until_id", input.until_id);
+    if (
+      (input.feed === "user" || input.feed === "mentions")
+      && typeof input.limit === "number"
+      && input.limit < 5
+    ) {
+      issues.push("input.limit must be at least 5 for user and mentions feeds");
+    }
+    if (
+      input.feed === "recent-search"
+      && typeof input.limit === "number"
+      && input.limit < 10
+    ) {
+      issues.push("input.limit must be at least 10 for recent-search");
+    }
+    for (const name of ["start_time", "end_time"] as const) {
+      const value = input[name];
+      if (
+        typeof value === "string"
+        && (
+          !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?Z$/u.test(value)
+          || !Number.isFinite(Date.parse(value))
+        )
+      ) {
+        issues.push(`input.${name} must be a valid UTC RFC 3339 timestamp`);
+      }
+    }
+  }
+  if (action === "posts.read" && Array.isArray(input.post_ids)) {
+    for (const [index, value] of input.post_ids.entries()) {
+      xId(`post_ids[${index}]`, value);
+    }
+    if (
+      input.post_ids.every((value) => typeof value === "string")
+      && new Set(input.post_ids).size !== input.post_ids.length
+    ) {
+      issues.push("input.post_ids must contain unique X post IDs");
+    }
+  }
+  if (action === "comments.read") xId("post_id", input.post_id);
+  if (action === "messaging.list") {
+    const needsTarget = input.view === "participant"
+      || input.view === "conversation"
+      || input.view === "chat-events";
+    if (needsTarget && typeof input.target_id !== "string") {
+      issues.push(
+        "input.target_id is required for participant, conversation, and chat-events views",
+      );
+    }
+    if (
+      (input.view === "all" || input.view === "chat-conversations")
+      && input.target_id !== undefined
+    ) {
+      issues.push(`input.target_id is not accepted when view is ${input.view}`);
+    }
+    if (input.view === "participant") xId("target_id", input.target_id);
+    if (input.view === "conversation") {
+      xConversationId("target_id", input.target_id);
+    }
+    if (
+      input.view === "chat-events"
+      && typeof input.target_id === "string"
+      && !/^(?:[0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$/u.test(
+        input.target_id,
+      )
+    ) {
+      issues.push(
+        "input.target_id must be an exact X Chat recipient or conversation ID",
+      );
+    }
+    if (
+      input.view === "chat-events"
+      && typeof input.target_id === "string"
+      && input.target_id.includes("-")
+    ) {
+      const [left, right] = input.target_id.split("-");
+      if (left === right) {
+        issues.push(
+          "input.target_id must identify two different X Chat participants",
+        );
+      }
+    }
+  }
+  if (action === "messaging.read") xId("event_id", input.event_id);
+  if (action === "messaging.send") {
+    if (input.target_kind === "participant") xId("target_id", input.target_id);
+    if (input.target_kind === "conversation") {
+      xConversationId("target_id", input.target_id);
+    }
+    if (
+      input.target_kind === "conversation"
+      && typeof input.target_id === "string"
+      && input.target_id.includes("-")
+    ) {
+      const [left, right] = input.target_id.split("-");
+      if (left === right) {
+        issues.push(
+          "input.target_id must identify two different legacy X DM participants",
+        );
+      }
+    }
+    if (typeof input.body !== "string" && !isFileInputValue(input.media)) {
+      issues.push("input.body or input.media is required for an X Direct Message");
+    }
+    if (input.media_alt_text !== undefined && !isFileInputValue(input.media)) {
+      issues.push("input.media_alt_text requires input.media");
+    }
+  }
+  if (action === "posts.publish") {
+    const hasPoll = Array.isArray(input.poll_options)
+      || input.poll_duration_minutes !== undefined;
+    if (
+      hasPoll
+      && (
+        !Array.isArray(input.poll_options)
+        || typeof input.poll_duration_minutes !== "number"
+      )
+    ) {
+      issues.push(
+        "input.poll_options and input.poll_duration_minutes must be supplied together",
+      );
+    }
+    if (hasPoll && Array.isArray(input.media)) {
+      issues.push("input.media and poll inputs are mutually exclusive");
+    }
+    if (
+      typeof input.body !== "string"
+      && !Array.isArray(input.media)
+      && !hasPoll
+    ) {
+      issues.push(
+        "input.body, input.media, or complete poll inputs are required for an X post",
+      );
+    }
+    if (input.made_with_ai === true && !Array.isArray(input.media)) {
+      issues.push(
+        "input.made_with_ai can be true only when reviewed media is attached",
+      );
+    }
+    if (input.media_alt_texts !== undefined) {
+      if (!Array.isArray(input.media)) {
+        issues.push("input.media_alt_texts requires input.media");
+      } else if (
+        !Array.isArray(input.media_alt_texts)
+        || input.media_alt_texts.length !== input.media.length
+      ) {
+        issues.push("input.media_alt_texts must align one-to-one with input.media");
+      }
+    }
+    xId("community_id", input.community_id);
+  }
+  if (action === "replies.create") {
+    xId("target_post_id", input.target_post_id);
+    if (typeof input.body !== "string" && !Array.isArray(input.media)) {
+      issues.push("input.body or input.media is required for an X reply");
+    }
+    if (input.media_alt_texts !== undefined) {
+      if (!Array.isArray(input.media)) {
+        issues.push("input.media_alt_texts requires input.media");
+      } else if (
+        !Array.isArray(input.media_alt_texts)
+        || input.media_alt_texts.length !== input.media.length
+      ) {
+        issues.push("input.media_alt_texts must align one-to-one with input.media");
+      }
+    }
+  }
+  if (action === "threads.publish") {
+    const media = input.media;
+    const indices = input.media_item_indices;
+    if (Array.isArray(media) !== Array.isArray(indices)) {
+      issues.push("input.media and input.media_item_indices must be supplied together");
+    }
+    if (
+      Array.isArray(media)
+      && Array.isArray(indices)
+      && media.length !== indices.length
+    ) {
+      issues.push("input.media_item_indices must align one-to-one with input.media");
+    }
+    if (Array.isArray(indices) && Array.isArray(input.items)) {
+      for (const [index, value] of indices.entries()) {
+        if (
+          typeof value === "number"
+          && (
+            !Number.isSafeInteger(value)
+            || value < 1
+            || value > input.items.length
+          )
+        ) {
+          issues.push(
+            `input.media_item_indices[${index}] must name an existing one-based thread item`,
+          );
+        }
+      }
+    }
+    if (input.media_alt_texts !== undefined) {
+      if (!Array.isArray(media)) {
+        issues.push("input.media_alt_texts requires input.media");
+      } else if (
+        !Array.isArray(input.media_alt_texts)
+        || input.media_alt_texts.length !== media.length
+      ) {
+        issues.push("input.media_alt_texts must align one-to-one with input.media");
+      }
+    }
+  }
+  if (action === "posts.repost" || action === "content.save") {
+    xId("post_id", input.post_id);
+  }
+  for (const name of ["limit", "poll_duration_minutes"] as const) {
+    const value = input[name];
+    if (typeof value === "number" && !Number.isSafeInteger(value)) {
+      issues.push(`input.${name} must be a safe integer`);
+    }
+  }
+  if (
+    (action === "articles.draft.save" || action === "articles.publish")
+    && input.cover_alt_text !== undefined
+    && !isFileInputValue(input.cover)
+  ) {
+    issues.push("input.cover_alt_text requires input.cover");
+  }
+  return issues;
+}

package/src/provider-contract-planning.ts

@@ -0,0 +1,23 @@
+import type { OperationInput } from "./model";
+import type { ProviderContract } from "./provider-contract-definitions";
+
+export function planProviderContractDispatches(
+  contract: ProviderContract,
+  input: OperationInput,
+): readonly { readonly id: string; readonly description: string }[] {
+  if (contract.dispatch === "none") return [];
+  if (contract.dispatch === "single") {
+    return [{
+      id: contract.operation.replaceAll(".", "-"),
+      description: `Execute ${contract.provider} ${contract.operation}`,
+    }];
+  }
+  const items = input.items;
+  if (!Array.isArray(items)) {
+    throw new Error("thread provider input must contain a validated items array");
+  }
+  return items.map((_item, index) => ({
+    id: `publish-item[${index + 1}]`,
+    description: `Publish confirmed thread item ${index + 1}`,
+  }));
+}

package/src/provider-contract-semantic-identity.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+
+function stableJson(value: unknown): string {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("provider plugin semantic identity contains a non-finite number");
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (typeof value === "object") {
+    const record = value as Readonly<Record<string, unknown>>;
+    return `{${Object.keys(record).sort().map((key) =>
+      `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+  }
+  throw new Error("provider plugin semantic identity contains an unsupported value");
+}
+
+/**
+ * Hash an exact provider-owned contract projection. Functions are deliberately
+ * excluded: shared planners are implementation sources, while provider-local
+ * validators are declared as provider-specific implementation sources.
+ */
+export function contractSemanticIdentity(
+  contracts: readonly object[],
+): string {
+  const ordered = [...contracts].sort((left, right) => {
+    const leftRecord = left as Readonly<Record<string, unknown>>;
+    const rightRecord = right as Readonly<Record<string, unknown>>;
+    const leftKey = `${String(leftRecord.provider ?? leftRecord.site)}/${String(leftRecord.operation)}@${String(leftRecord.contractVersion)}`;
+    const rightKey = `${String(rightRecord.provider ?? rightRecord.site)}/${String(rightRecord.operation)}@${String(rightRecord.contractVersion)}`;
+    return leftKey.localeCompare(rightKey);
+  });
+  return createHash("sha256").update(stableJson(ordered)).digest("hex");
+}
+
+export function assertContractSemanticIdentity(
+  owner: string,
+  contracts: readonly object[],
+  expected: string,
+): void {
+  if (!/^[a-f0-9]{64}$/u.test(expected)) {
+    throw new Error(`${owner} contract semantic identity must be a lowercase SHA-256 digest`);
+  }
+  const actual = contractSemanticIdentity(contracts);
+  if (actual !== expected) {
+    throw new Error(
+      `${owner} contract semantics changed: expected ${expected}, received ${actual}`,
+    );
+  }
+}