@nodaro/shared 3.11.0 → 3.12.0

package/src/instagram-scrape.ts

@@ -0,0 +1,204 @@
+/**
+ * Instagram scraper node — shared vocabulary + credit identifiers.
+ *
+ * Pulls PUBLIC Instagram posts (feed images, carousels, reels) by profile or
+ * by hashtag and emits a normalized JSON array. Same shape of contract as the
+ * Meta Ads node: everything the backend guard/reservation, the frontend credit
+ * badge and the docs formula must agree on lives here.
+ *
+ * Pricing: 1 credit per REQUESTED post, rounded UP to a fixed tier of
+ * `count × sources` (a profile / hashtag is one source, up to 5). Optional
+ * per-post AI analysis folds into the same identifier, priced by the model's
+ * tier — reusing the Meta analysis per-item values so the two nodes stay in
+ * lockstep.
+ */
+import {
+  META_ADS_ANALYSIS_CREDITS_PER_AD,
+  META_ADS_ANALYSIS_TIERS,
+  metaAdsAnalysisTier,
+  type MetaAdsAnalysisTier,
+} from "./meta-ads-scrape.js"
+import { classifyCreativeFormat, type MetaAdsFormat } from "./meta-ads-scrape.js"
+
+export const INSTAGRAM_SCRAPE_NODE_TYPE = "instagram-scrape" as const
+
+export const INSTAGRAM_SCRAPE_MODES = ["profile", "hashtag"] as const
+export type InstagramScrapeMode = (typeof INSTAGRAM_SCRAPE_MODES)[number]
+
+export function isInstagramScrapeMode(value: unknown): value is InstagramScrapeMode {
+  return typeof value === "string" && (INSTAGRAM_SCRAPE_MODES as readonly string[]).includes(value)
+}
+export function instagramScrapeMode(value: unknown): InstagramScrapeMode {
+  return isInstagramScrapeMode(value) ? value : "profile"
+}
+
+/** Same window vocabulary as Meta Ads; the Instagram actor honours it server-side (`onlyPostsNewerThan`). */
+export const INSTAGRAM_SCRAPE_PERIODS = ["24h", "7d", "30d", "all"] as const
+export type InstagramScrapePeriod = (typeof INSTAGRAM_SCRAPE_PERIODS)[number]
+
+export const INSTAGRAM_SCRAPE_DEFAULT_COUNT = 20
+export const INSTAGRAM_SCRAPE_MAX_COUNT = 100
+export const INSTAGRAM_SCRAPE_MAX_SOURCES = 5
+/** Instagram usernames / hashtags are short; cap a single target well under a URL. */
+export const INSTAGRAM_SCRAPE_MAX_TARGET_LENGTH = 200
+
+/** Requested-total buckets — identical shape to Meta (the pricing model is the same). */
+export const INSTAGRAM_SCRAPE_TIERS = [10, 20, 50, 100, 200, 500] as const
+export type InstagramScrapeTier = (typeof INSTAGRAM_SCRAPE_TIERS)[number]
+
+export function instagramScrapeTier(requestedTotal: number): InstagramScrapeTier {
+  for (const tier of INSTAGRAM_SCRAPE_TIERS) if (requestedTotal <= tier) return tier
+  return INSTAGRAM_SCRAPE_TIERS[INSTAGRAM_SCRAPE_TIERS.length - 1]
+}
+
+/** The analysis tier a request / node asks for, or null when analysis is off. */
+export function instagramAnalysisTierFrom(data: { readonly analyze?: unknown; readonly analysisModel?: unknown }): MetaAdsAnalysisTier | null {
+  return data.analyze === true ? metaAdsAnalysisTier(data.analysisModel) : null
+}
+
+function analysisSuffix(tier: MetaAdsAnalysisTier): string {
+  return tier === "standard" ? ":analysis" : `:analysis:${tier}`
+}
+
+/** Per-post settlement SKU for a tier (the bare id is the standard tier). */
+export const INSTAGRAM_ANALYSIS_CREDIT_ID = "instagram-analysis" as const
+export function instagramAnalysisCreditId(tier: MetaAdsAnalysisTier): string {
+  return tier === "standard" ? INSTAGRAM_ANALYSIS_CREDIT_ID : `${INSTAGRAM_ANALYSIS_CREDIT_ID}:${tier}`
+}
+
+export interface InstagramScrapeCreditInput {
+  count: number
+  sources: number
+  analysis?: MetaAdsAnalysisTier | null
+}
+
+export function buildInstagramScrapeCreditId(input: InstagramScrapeCreditInput): string {
+  const sources = Math.min(Math.max(Math.trunc(input.sources) || 1, 1), INSTAGRAM_SCRAPE_MAX_SOURCES)
+  const count = Math.min(Math.max(Math.trunc(input.count) || 1, 1), INSTAGRAM_SCRAPE_MAX_COUNT)
+  const base = `${INSTAGRAM_SCRAPE_NODE_TYPE}:${instagramScrapeTier(count * sources)}`
+  return input.analysis ? `${base}${analysisSuffix(input.analysis)}` : base
+}
+
+/**
+ * Cost per SKU — mirror of the backend `STATIC_CREDIT_COSTS` rows / migration,
+ * for the frontend badge / estimator. 1 credit per requested post at every
+ * tier, plus the analysis multiples.
+ */
+export const INSTAGRAM_SCRAPE_CREDIT_COSTS: Record<string, number> = (() => {
+  const table: Record<string, number> = { [INSTAGRAM_SCRAPE_NODE_TYPE]: 20 }
+  for (const tier of META_ADS_ANALYSIS_TIERS) table[instagramAnalysisCreditId(tier)] = META_ADS_ANALYSIS_CREDITS_PER_AD[tier]
+  for (const t of INSTAGRAM_SCRAPE_TIERS) {
+    table[`${INSTAGRAM_SCRAPE_NODE_TYPE}:${t}`] = t
+    for (const tier of META_ADS_ANALYSIS_TIERS) {
+      table[`${INSTAGRAM_SCRAPE_NODE_TYPE}:${t}${analysisSuffix(tier)}`] = t * (1 + META_ADS_ANALYSIS_CREDITS_PER_AD[tier])
+    }
+  }
+  return table
+})()
+
+export const INSTAGRAM_SCRAPE_FALLBACK_CREDIT_ID = "instagram-scrape:20"
+
+export function isInstagramScrapeCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= INSTAGRAM_SCRAPE_MAX_COUNT
+}
+
+/**
+ * Targets (profile usernames/URLs or hashtags) are typed one per line; the
+ * route wants an array. Unlike page urls a target can be a bare username /
+ * `#tag`, so split on lines / commas only (never whitespace), strip a leading
+ * `@` or `#`, dedupe, cap at MAX_SOURCES.
+ */
+export function splitInstagramTargets(value: unknown): string[] {
+  const raw = Array.isArray(value)
+    ? value.filter((v): v is string => typeof v === "string")
+    : typeof value === "string"
+      ? value.split(/[\n,]+/)
+      : []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const item of raw) {
+    const t = item.trim().replace(/^[@#]+/, "").trim()
+    if (t.length < 1 || t.length > INSTAGRAM_SCRAPE_MAX_TARGET_LENGTH) continue
+    const key = t.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(t)
+    if (out.length >= INSTAGRAM_SCRAPE_MAX_SOURCES) break
+  }
+  return out
+}
+
+/** The featured post index, clamped. */
+export function clampInstagramFeaturedIndex(stored: unknown, count: number): number {
+  if (count <= 0) return 0
+  const n = typeof stored === "number" && Number.isFinite(stored) ? Math.trunc(stored) : 0
+  return Math.min(Math.max(n, 0), count - 1)
+}
+
+export interface FeaturedInstagramOutputs {
+  readonly text?: string
+  readonly imageUrl?: string
+  readonly videoUrl?: string
+}
+
+function urlStrings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === "string" && v.trim().length > 0) : []
+}
+
+/** The featured post's caption (`text`), first image / cover (`image`), and first video (`video`). */
+export function featuredInstagramOutputs(json: unknown, featuredIndex: unknown): FeaturedInstagramOutputs {
+  if (!Array.isArray(json) || json.length === 0) return {}
+  const post = json[clampInstagramFeaturedIndex(featuredIndex, json.length)]
+  if (!post || typeof post !== "object") return {}
+  const p = post as Record<string, unknown>
+  const text = typeof p.caption === "string" ? p.caption.trim() : ""
+  const imageUrl = urlStrings(p.images)[0] ?? urlStrings(p.videoPreviews)[0]
+  const videoUrl = urlStrings(p.videos)[0]
+  return {
+    ...(text ? { text } : {}),
+    ...(imageUrl ? { imageUrl } : {}),
+    ...(videoUrl ? { videoUrl } : {}),
+  }
+}
+
+/** The node-data fields a quote reads. */
+export interface InstagramNodeQuoteFields {
+  readonly [key: string]: unknown
+  readonly mode?: unknown
+  readonly targets?: unknown
+  readonly count?: unknown
+  readonly analyze?: unknown
+  readonly analysisModel?: unknown
+}
+
+/** Billable source count: number of targets (min 1). */
+export function instagramScrapeSources(data: InstagramNodeQuoteFields): number {
+  return Math.max(1, Math.min(splitInstagramTargets(data.targets).length, INSTAGRAM_SCRAPE_MAX_SOURCES))
+}
+
+/** The ONE credit identifier for a node's current settings. */
+export function instagramScrapeCreditIdFromNode(data: InstagramNodeQuoteFields): string {
+  const count = typeof data.count === "number" ? data.count : INSTAGRAM_SCRAPE_DEFAULT_COUNT
+  return buildInstagramScrapeCreditId({ count, sources: instagramScrapeSources(data), analysis: instagramAnalysisTierFrom(data) })
+}
+
+/**
+ * Resolve the credit identifier from an UNVALIDATED request body (the guard
+ * runs before Zod). Lands on the SAME tier the reservation computes.
+ */
+export function resolveInstagramScrapeCreditId(body: unknown): string {
+  const raw = body as { count?: unknown; targets?: unknown; analyze?: unknown; analysisModel?: unknown } | null | undefined
+  if (!raw || typeof raw !== "object") return INSTAGRAM_SCRAPE_FALLBACK_CREDIT_ID
+  const count = raw.count === undefined ? INSTAGRAM_SCRAPE_DEFAULT_COUNT : raw.count
+  if (!isInstagramScrapeCount(count)) return INSTAGRAM_SCRAPE_FALLBACK_CREDIT_ID
+  // Same splitter the handler uses for `sources` (dedupes, caps at MAX), so the
+  // pre-Zod guard and the post-Zod reservation always land on the same tier —
+  // a duplicate target bills once, not per copy.
+  const sources = splitInstagramTargets(raw.targets).length
+  if (sources < 1) return INSTAGRAM_SCRAPE_FALLBACK_CREDIT_ID
+  return buildInstagramScrapeCreditId({ count, sources, analysis: instagramAnalysisTierFrom(raw) })
+}
+
+// Re-export the shared creative-format vocabulary so the node imports one place.
+export { classifyCreativeFormat }
+export type InstagramFormat = MetaAdsFormat

package/src/llm-models.ts

@@ -118,12 +118,37 @@ export interface LlmModelDef {
    *
    * Consumers MUST give such a model output headroom regardless of the
    * requested effort, or reasoning silently eats a small legacy cap and the
-   * answer truncates with `stop_reason: max_tokens` — a paid-for empty reply,
-   * not an error. `deriveParams` (llm-client.ts) and the film-pipeline's
-   * `callLLM` both floor on this flag; keep it in sync with the vendor's
+   * answer truncates with `stop_reason: max_tokens` — a paid-for empty reply
+   * (since #1588 the client fails such a call rather than return the
+   * fragment, but the floor is what keeps it from happening). `deriveParams`
+   * (llm-client.ts) floors to {@link reasoningOutputFloor}; the film
+   * pipeline's `callLLM` — Anthropic SDK only, so only its Claude members
+   * matter — floors at the default. Keep the flag in sync with the vendor's
    * documented default rather than inferring it from the model name.
    */
   thinkingDefaultOn?: true
+  /**
+   * The output-token cap a REASONING call on this model is floored to — the
+   * room its thinking shares with the answer (`thinkingDefaultOn`, or an
+   * xhigh/max effort). Absent = {@link REASONING_OUTPUT_FLOOR}; read it through
+   * {@link reasoningOutputFloor}, never directly.
+   *
+   * Declare it ONLY where a lane serving this model is not known to accept the
+   * default: the floor rides every lane the model can be served on (KIE AND its
+   * direct fallback), so it has to sit at the intersection of what they take —
+   * the rule `maxOutputTokens` already follows for the Gemini flash entries.
+   * Never below `maxOutputTokens` (a floor under the default cap is not a
+   * floor — guarded by a registry test).
+   */
+  reasoningOutputFloor?: number
+}
+
+/** The reasoning floor for a model that declares no lane limit of its own. */
+export const REASONING_OUTPUT_FLOOR = 32768
+
+/** The output cap a reasoning call on `model` is floored to (see `LlmModelDef.reasoningOutputFloor`). */
+export function reasoningOutputFloor(model: LlmModelDef): number {
+  return model.reasoningOutputFloor ?? REASONING_OUTPUT_FLOOR
 }
 
 export const LLM_MODELS: readonly LlmModelDef[] = [
@@ -145,6 +170,11 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     // No `reasoningEfforts` at all on the KIE lane, but the vendor API accepts
     // the full minimal→high ladder (`none` maps to Google's `minimal`).
     directReasoningEfforts: ["none", "low", "medium", "high"],
+    // Reasons with no thinking param sent — Google's Gemini 3 default (dynamic
+    // thinking; `minimal` is its floor, never off), measured on 3.6 in #1588.
+    // Floored at the KIE-safe 8192, the same intersection as `maxOutputTokens`.
+    thinkingDefaultOn: true,
+    reasoningOutputFloor: 8192,
   },
   {
     id: "gemini-3.6-flash",
@@ -177,6 +207,15 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     // Gemini entry — the lane with the lower unit cost wins by default and
     // direct is the reliability fallback only.
     directGeminiModel: "gemini-3.6-flash",
+    // Reasons with NO thinking param sent — measured, issue #1588: a Generate
+    // Text node capped at 1,100 tokens fell back to the direct lane (KIE 500),
+    // spent ~1,060 of them reasoning, and returned 120 characters cut mid-URL.
+    // On the same input the KIE runs used ~500 output tokens in all, so only
+    // the fallback runs broke — every other run of a 5-minute schedule.
+    // Floored at 8192, NOT the default 32768: the floor rides the KIE endpoint
+    // too, and 8192 is all it is known to take (see `maxOutputTokens`).
+    thinkingDefaultOn: true,
+    reasoningOutputFloor: 8192,
   },
   {
     id: "gemini-3.7-flash",
@@ -205,6 +244,10 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     // Assumed parity with 3.6 pending a live probe on the direct lane.
     directReasoningEfforts: ["none", "low", "medium", "high"],
     directGeminiModel: "gemini-3.7-flash",
+    // Gemini 3 default: reasons with no thinking param sent (measured on 3.6,
+    // #1588). KIE-safe floor, same intersection as `maxOutputTokens`.
+    thinkingDefaultOn: true,
+    reasoningOutputFloor: 8192,
   },
   {
     id: "gemini-3.8-flash",
@@ -245,6 +288,11 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     // KIE-first (no `preferDirect`) — 3.7's posture exactly: the cheap lane
     // serves the A/B, direct is Advanced mode + the reliability fallback.
     directGeminiModel: "gemini-3.8-flash",
+    // Gemini 3 default: reasons with no thinking param sent (measured on 3.6,
+    // #1588). Floored at its own 16384, inside the 20000 its KIE endpoint was
+    // measured to honour.
+    thinkingDefaultOn: true,
+    reasoningOutputFloor: 16384,
   },
   {
     id: "claude-haiku-4.5",
@@ -318,6 +366,11 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     // `additionalProperties` (KIE's `response_format` silently DROPS
     // record/map-shaped fields — see the z.record rule in backend/CLAUDE.md).
     preferDirect: true,
+    // Reasons with no thinking param sent on both lanes — the proxied endpoint
+    // DEFAULTS to "high" (above), and the direct lane reasons harder still.
+    // Floored at its own 16384: its KIE fallback is not known to take more.
+    thinkingDefaultOn: true,
+    reasoningOutputFloor: 16384,
   },
   {
     id: "claude-opus-4.7",
@@ -413,6 +466,22 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     maxOutputTokens: 16384,
     reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
     supportsTemperature: false,
+    // SERVED COLLAPSED, on the astra precedent (2026-09-17). The 2026-07-14
+    // verification that KIE's non-stream responses endpoint serves the GPT-5.6
+    // family reliably no longer holds: a live call — a recast continuity
+    // review, ~3k tokens, `reasoning.effort: high`, `text.format: json_schema`
+    // — came back `500 {"error":{"type":"server_error"}}` / "Server exception,
+    // please try again later". Same endpoint family, same dialect and the same
+    // signature astra was measured on (12 calls: non-stream 2/6, streaming
+    // 5/6; a schema-less non-stream call 500'd too, so the lane is the trigger
+    // and not the schema). ONE sighting here rather than a fresh 12-call probe
+    // — the precedent is strong and the flag is cheap to reverse.
+    //
+    // THE COST: SSE does not reliably carry `credits_consumed`, so this model's
+    // provider cost becomes the rate-table estimate instead of the billed
+    // figure. That is the price of a lane that answers, and it is the same
+    // trade astra already makes.
+    kieCollapseStream: true,
   },
   {
     id: "gpt-6-astra",
@@ -649,6 +718,10 @@ export type LlmFeature =
   // zero-cost `3d-scene-ops` identifier instead.
   | "3d-scene"
   | "image-to-text"
+  // Per-ad creative analysis on the social scraper nodes (Meta Ads first):
+  // one structured vision call per ad, priced per REQUESTED ad by tier and
+  // folded into the scrape's own identifier (packages/shared/meta-ads-scrape).
+  | "meta-ads-analysis"
   | "describe-to-picker"
   | "qa-check"
   | "generate-script"
@@ -680,6 +753,10 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
   "3d-title": "claude-sonnet-4.6",
   "3d-scene": "claude-sonnet-4.6",
   "image-to-text": "claude-sonnet-4.6",
+  // Economy on purpose: the analysis reads ONE frame + the copy per ad and
+  // runs once per returned ad — volume, not depth. Must stay an image-capable
+  // structured-output model (STRUCTURED_VISION_MODELS); a registry test pins it.
+  "meta-ads-analysis": "gemini-3.6-flash",
   "describe-to-picker": "claude-opus-5",
   "qa-check": "gemini-3.6-flash",
   "generate-script": "gemini-3.6-flash",