@whereamimentioned/api-client 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1105 @@
+// src/contract.ts
+import { z } from "zod";
+
+// src/enums.ts
+var ORG_TYPES = ["agency", "brand"];
+var ORG_ROLES = ["owner", "admin", "member", "viewer"];
+var TIERS = ["free", "single", "pro", "agency", "enterprise"];
+var INTENT_STAGES = ["awareness", "research", "comparison", "purchase", "branded"];
+var PROMPT_TYPES = [
+  "category",
+  "competitor_comparison",
+  "use_case",
+  "persona_need",
+  "branded"
+];
+var PROMPT_SOURCES = ["generated", "template", "custom"];
+var SENTIMENTS = ["positive", "neutral", "negative", "not_present"];
+var SCAN_STATUSES = ["queued", "running", "done", "failed"];
+var SCAN_MODES = ["grounded", "raw", "both"];
+var CITATION_BUCKETS = ["owned", "competitor", "third_party"];
+var RECOMMENDATION_STATUSES = ["open", "done", "dismissed"];
+var RECOMMENDATION_TYPES = [
+  "losing_prompt",
+  "power_source",
+  "low_prominence",
+  "reputation_risk",
+  "citation_gap",
+  "ai_readiness"
+];
+var REPORT_FORMATS = ["pdf", "csv", "json"];
+var API_SCOPES = [
+  "workspaces:read",
+  "workspaces:write",
+  "scans:read",
+  "scans:write",
+  "reports:read",
+  "prompts:read",
+  "prompts:write",
+  "competitors:read",
+  "competitors:write",
+  "orgs:write"
+];
+var READ_ONLY_SCOPES = [
+  "workspaces:read",
+  "scans:read",
+  "reports:read",
+  "prompts:read",
+  "competitors:read"
+];
+
+// src/contract.ts
+var API_KEY_KINDS = ["org", "user"];
+var API_KEY_ENVS = ["live", "test"];
+var API_VERSION = 1;
+var API_VERSION_HEADER = "X-Wam-Api-Version";
+var IDEMPOTENT_REPLAY_HEADER = "X-Idempotent-Replay";
+var API_ERROR_CODES = [
+  "bad_request",
+  // 400 (body not parseable as JSON at all)
+  "unauthorized",
+  // 401
+  "insufficient_role",
+  // 403
+  "insufficient_scope",
+  // 403
+  "feature_not_available",
+  // 403 (tier gate)
+  "not_found",
+  // 404
+  "conflict",
+  // 409
+  "scan_already_running",
+  // 409
+  "validation_failed",
+  // 422
+  "insufficient_credits",
+  // 402
+  "rate_limited",
+  // 429
+  "internal_error"
+  // 500
+];
+var requestId = z.string().regex(/^req_[0-9A-HJKMNP-TV-Z]{26}$/);
+var apiErrorBody = z.object({
+  error: z.object({
+    code: z.enum(API_ERROR_CODES),
+    message: z.string(),
+    /** Correlates with Sentry and with the server log line. Always present. */
+    requestId: z.string(),
+    /** Code-specific structured payload. Never free-form prose. */
+    details: z.record(z.string(), z.unknown()).optional()
+  })
+});
+var insufficientCreditsDetails = z.object({
+  required: z.number().int(),
+  available: z.number().int(),
+  billingUrl: z.string().url()
+});
+var rateLimitedDetails = z.object({
+  retryAfterSeconds: z.number().int().nonnegative()
+});
+var scanAlreadyRunningDetails = z.object({
+  scanId: z.string(),
+  pollUrl: z.string()
+});
+var conflictDetails = z.object({
+  originalScanId: z.string().optional(),
+  originalOrgId: z.string().optional(),
+  limit: z.number().int().optional(),
+  current: z.number().int().optional(),
+  tier: z.enum(TIERS).optional(),
+  billingUrl: z.string().url().optional(),
+  fields: z.array(z.string()).optional()
+});
+var featureNotAvailableDetails = z.object({
+  billingUrl: z.string().url().optional(),
+  limit: z.number().int().optional(),
+  current: z.number().int().optional(),
+  allowedFormats: z.array(z.enum(REPORT_FORMATS)).optional()
+});
+var validationFailedDetails = z.object({
+  hint: z.string().optional(),
+  issues: z.array(z.object({ path: z.array(z.union([z.string(), z.number()])), message: z.string() })).optional()
+});
+var reportNotFoundDetails = z.object({
+  status: z.enum(SCAN_STATUSES)
+});
+var API_ERROR_DETAILS = {
+  insufficient_credits: insufficientCreditsDetails,
+  rate_limited: rateLimitedDetails,
+  scan_already_running: scanAlreadyRunningDetails,
+  conflict: conflictDetails,
+  feature_not_available: featureNotAvailableDetails,
+  validation_failed: validationFailedDetails
+};
+function parseErrorDetails(code, details) {
+  const parsed = API_ERROR_DETAILS[code].safeParse(details);
+  return parsed.success ? parsed.data : void 0;
+}
+var pagination = z.object({
+  /** Opaque. `null` on the last page, and that (never an empty `data`) is the end signal. */
+  nextCursor: z.string().nullable(),
+  hasMore: z.boolean(),
+  limit: z.number().int().min(1).max(100)
+});
+function page(item) {
+  return z.object({ data: z.array(item), pagination });
+}
+var pageQuery = z.object({
+  limit: z.number().int().min(1).max(100).optional(),
+  cursor: z.string().optional(),
+  /** 08 section 4.6: list endpoints only, intersected with the serializer allowlist. */
+  fields: z.array(z.string().min(1)).optional()
+}).strict();
+var scanListQuery = pageQuery.extend({
+  status: z.enum(SCAN_STATUSES).optional(),
+  /** ISO 8601 date or date-time, inclusive, against `created_at`. */
+  from: z.string().optional(),
+  to: z.string().optional()
+}).strict();
+var promptListQuery = pageQuery.extend({
+  enabled: z.boolean().optional(),
+  source: z.enum(PROMPT_SOURCES).optional(),
+  stage: z.enum(INTENT_STAGES).optional()
+}).strict();
+var answerListQuery = pageQuery.extend({
+  modelId: z.string().optional(),
+  mentioned: z.boolean().optional(),
+  lowConfidence: z.boolean().optional()
+}).strict();
+var recommendationListQuery = pageQuery.extend({
+  scanId: z.string().optional(),
+  status: z.enum(RECOMMENDATION_STATUSES).optional(),
+  type: z.enum(RECOMMENDATION_TYPES).optional()
+}).strict();
+var citationListQuery = pageQuery.extend({
+  scanId: z.string().optional(),
+  bucket: z.enum(CITATION_BUCKETS).optional()
+}).strict();
+var meResponse = z.object({
+  key: z.object({
+    id: z.string(),
+    name: z.string(),
+    /** Display only, e.g. "wam_live_7Ka3Qp2m". Never sufficient to authenticate. */
+    prefix: z.string(),
+    last4: z.string(),
+    kind: z.enum(API_KEY_KINDS),
+    env: z.enum(API_KEY_ENVS),
+    scopes: z.array(z.enum(API_SCOPES)),
+    roleCeiling: z.enum(ORG_ROLES),
+    expiresAt: z.string().nullable()
+  }),
+  org: z.object({
+    id: z.string(),
+    slug: z.string(),
+    name: z.string(),
+    type: z.enum(ORG_TYPES)
+  }),
+  actor: z.object({
+    userId: z.string(),
+    role: z.enum(ORG_ROLES),
+    effectiveRole: z.enum(ORG_ROLES)
+  }),
+  plan: z.object({
+    tier: z.enum(TIERS),
+    /** TIER_FEATURES[tier].label verbatim. */
+    label: z.string(),
+    mcp: z.boolean(),
+    /** File download formats only; format=json on the report route is never gated. */
+    exportFormats: z.array(z.enum(REPORT_FORMATS)),
+    promptsPerWorkspace: z.number().int(),
+    maxScanPrompts: z.number().int()
+  }),
+  credits: z.object({
+    balance: z.number().int(),
+    /** CREDIT_UNIT_DESCRIPTION served verbatim. Never paraphrase it in a client or a fixture. */
+    unit: z.string()
+  })
+});
+var organizationSummary = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  tier: z.enum(TIERS),
+  /** min(live role, roleCeiling): the power the caller actually gets, not the raw membership. */
+  effectiveRole: z.enum(ORG_ROLES),
+  workspaceCount: z.number().int()
+});
+var createOrganizationBody = z.object({
+  name: z.string().trim().min(1).max(120),
+  type: z.enum(ORG_TYPES)
+}).strict();
+var createOrganizationResult = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  type: z.enum(ORG_TYPES),
+  tier: z.enum(TIERS),
+  /** Always false on a fresh create; recomputed as tier !== "free" on an idempotent replay (08 section 7.3). */
+  usable: z.boolean(),
+  subscribeUrl: z.string().url(),
+  /** User-visible copy. Print it verbatim. Present only while `usable` is false (08 section 7.3). */
+  message: z.string().optional()
+}).superRefine((v, ctx) => {
+  if (!v.usable && v.message === void 0) {
+    ctx.addIssue({ code: "custom", path: ["message"], message: "message is required while usable is false" });
+  }
+  if (v.usable && v.message !== void 0) {
+    ctx.addIssue({ code: "custom", path: ["message"], message: "message must be absent when usable is true" });
+  }
+});
+var latestScanRef = z.object({
+  id: z.string(),
+  status: z.enum(SCAN_STATUSES),
+  finishedAt: z.string().nullable(),
+  score: z.number().nullable()
+});
+var workspaceSummary = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  brandName: z.string().nullable(),
+  defaultRegion: z.string(),
+  defaultLanguage: z.string(),
+  /** Boolean only. The key itself, encrypted or not, never leaves the server. */
+  usesOwnKey: z.boolean(),
+  promptCount: z.number().int(),
+  enabledPromptCount: z.number().int(),
+  /** null when the workspace has never completed a scan. */
+  latestScan: latestScanRef.nullable(),
+  /** null when nothing is queued or running. */
+  activeScanId: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var workspaceDetail = workspaceSummary.extend({
+  competitorCount: z.number().int()
+});
+var createWorkspaceBody = z.object({
+  name: z.string().trim().min(1).max(120)
+}).strict();
+var competitor = z.object({
+  id: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  aliases: z.array(z.string()),
+  createdAt: z.string()
+});
+var createCompetitorBody = z.object({
+  name: z.string().trim().min(1).max(120),
+  domain: z.string().trim().max(253).optional(),
+  aliases: z.array(z.string().trim().min(1).max(120)).max(20).default([])
+}).strict();
+var prompt = z.object({
+  id: z.string(),
+  text: z.string(),
+  intentStage: z.enum(INTENT_STAGES),
+  persona: z.string(),
+  type: z.enum(PROMPT_TYPES),
+  topic: z.string().nullable(),
+  isBranded: z.boolean(),
+  tags: z.array(z.string()),
+  source: z.enum(PROMPT_SOURCES),
+  enabled: z.boolean(),
+  createdAt: z.string()
+});
+var promptListResponse = page(prompt).extend({
+  promptsPerWorkspace: z.number().int(),
+  maxScanPrompts: z.number().int()
+});
+var createPromptBody = z.object({
+  text: z.string().trim().min(8).max(400),
+  intentStage: z.enum(INTENT_STAGES).default("research"),
+  persona: z.string().trim().max(80).optional(),
+  enabled: z.boolean().default(true)
+}).strict();
+var patchPromptBody = z.object({
+  enabled: z.boolean()
+}).strict();
+var deletePromptResult = z.object({
+  deleted: z.literal(true),
+  id: z.string()
+});
+var scanSummary = z.object({
+  id: z.string(),
+  status: z.enum(SCAN_STATUSES),
+  mode: z.enum(SCAN_MODES),
+  repetitions: z.number().int(),
+  /** modelIds.length as stored: the roster the scan actually ran with. */
+  modelCount: z.number().int(),
+  /** The stored prompt_count column, never recomputed. */
+  promptCount: z.number().int(),
+  creditsSpent: z.number().int().nullable(),
+  /** The overall ai_visibility_score, null until done. */
+  score: z.number().nullable(),
+  createdAt: z.string(),
+  startedAt: z.string().nullable(),
+  finishedAt: z.string().nullable(),
+  error: z.string().nullable()
+});
+var scanProgress = z.object({
+  done: z.number().int(),
+  /**
+   * Grows while the scan runs (adaptive re-runs are planned as it goes), so a naive done/total
+   * percentage moves backwards. Render a percentage only when `totalIsFinal` is true.
+   */
+  total: z.number().int(),
+  /** status === "done" || status === "failed". */
+  totalIsFinal: z.boolean()
+});
+var scanStatus = z.object({
+  id: z.string(),
+  workspaceSlug: z.string(),
+  status: z.enum(SCAN_STATUSES),
+  mode: z.enum(SCAN_MODES),
+  repetitions: z.number().int(),
+  progress: scanProgress,
+  creditsReserved: z.number().int(),
+  creditsSpent: z.number().int().nullable(),
+  score: z.number().nullable(),
+  createdAt: z.string(),
+  startedAt: z.string().nullable(),
+  finishedAt: z.string().nullable(),
+  error: z.string().nullable()
+});
+var scanModelRef = z.object({
+  id: z.string(),
+  displayName: z.string()
+});
+var scanEstimate = z.object({
+  /** prompts x models.length x repetitions (x2 when mode is "both"). Tier-derived, never a constant. */
+  credits: z.number().int(),
+  prompts: z.number().int(),
+  models: z.array(scanModelRef),
+  repetitions: z.number().int(),
+  mode: z.enum(SCAN_MODES),
+  balance: z.number().int(),
+  sufficient: z.boolean(),
+  /** BYOK reserves zero credits and skips the ledger. */
+  usesOwnKey: z.boolean(),
+  quote: z.object({
+    token: z.string(),
+    expiresAt: z.string()
+  })
+});
+var estimateScanBody = z.object({}).strict();
+var createScanBody = z.object({
+  /** Optional here, MANDATORY on the MCP run_scan tool (08 section 6.5). */
+  quote: z.string().optional()
+}).strict();
+var createScanResult = z.object({
+  id: z.string(),
+  status: z.enum(SCAN_STATUSES),
+  credits: z.number().int(),
+  prompts: z.number().int(),
+  models: z.number().int(),
+  /** The balance now on an idempotent replay, the balance at creation on a 201. */
+  balanceAfter: z.number().int(),
+  pollUrl: z.string()
+});
+var idempotencyKey = z.string().regex(/^[A-Za-z0-9_.:-]{1,128}$/);
+var ANSWER_TEXT_MAX_CHARS = 1200;
+var ANSWER_CITATIONS_MAX = 25;
+var answerCitation = z.object({
+  url: z.string(),
+  domain: z.string()
+});
+var brandPresent = z.object({
+  name: z.string(),
+  is_target: z.boolean(),
+  rank: z.number().int().nullable()
+});
+var scanAnswer = z.object({
+  answerId: z.string(),
+  promptId: z.string(),
+  promptText: z.string(),
+  intentStage: z.enum(INTENT_STAGES),
+  modelId: z.string(),
+  modelName: z.string(),
+  grounded: z.boolean(),
+  brandMentioned: z.boolean(),
+  brandPosition: z.number().int().nullable(),
+  sentiment: z.enum(SENTIMENTS),
+  brandsPresent: z.array(brandPresent),
+  citations: z.array(answerCitation).max(ANSWER_CITATIONS_MAX),
+  confidence: z.number(),
+  lowConfidence: z.boolean(),
+  /** Truncated to 1200 characters. Full answer text is never returned by the API. */
+  answerText: z.string().max(ANSWER_TEXT_MAX_CHARS),
+  answerTextTruncated: z.boolean()
+});
+var recommendation = z.object({
+  id: z.string(),
+  type: z.enum(RECOMMENDATION_TYPES),
+  title: z.string(),
+  body: z.string(),
+  impact: z.number().int(),
+  effort: z.number().int(),
+  priority: z.number(),
+  status: z.enum(RECOMMENDATION_STATUSES),
+  scanId: z.string().nullable(),
+  createdAt: z.string()
+});
+var citation = z.object({
+  domain: z.string(),
+  count: z.number().int(),
+  share: z.number(),
+  bucket: z.enum(CITATION_BUCKETS)
+});
+var credits = z.object({
+  balance: z.number().int(),
+  tier: z.enum(TIERS),
+  monthlyCredits: z.number().int(),
+  /** CREDIT_UNIT_DESCRIPTION verbatim. */
+  unit: z.string(),
+  /** Scans remaining at the maximum scan size for your tier. Never "for workspace X". */
+  estimatedScansRemaining: z.number().int()
+});
+var revokeSelfQuery = z.object({ all: z.literal("cli").optional() }).strict();
+var revokeSelfResult = z.object({
+  revoked: z.number().int(),
+  self: z.literal(true),
+  scope: z.literal("cli").optional()
+});
+var quotePayload = z.object({
+  /** Payload version. Bumped if any field below changes meaning. */
+  v: z.literal(1),
+  orgId: z.string(),
+  workspaceId: z.string(),
+  /** The key this quote was minted FOR. */
+  keyId: z.string(),
+  promptCount: z.number().int(),
+  /** The resolved roster, by id, not a count. */
+  modelIds: z.array(z.string()),
+  repetitions: z.number().int(),
+  mode: z.enum(SCAN_MODES),
+  creditCost: z.number().int(),
+  /** BYOK reserves zero credits, so a BYOK quote is not interchangeable with a metered one. */
+  byok: z.boolean(),
+  iat: z.number().int(),
+  exp: z.number().int()
+});
+var QUOTE_TTL_SECONDS = 300;
+var reportData = z.object({
+  /** The scan the report describes (08 section 4.8): on the interface itself, not added by a client. */
+  scanId: z.string(),
+  brandName: z.string(),
+  workspaceName: z.string(),
+  scanDate: z.string(),
+  score: z.number(),
+  presenceRate: z.number(),
+  presenceCiLow: z.number(),
+  presenceCiHigh: z.number(),
+  sov: z.number(),
+  sentimentScore: z.number().nullable(),
+  brandCitationShare: z.number(),
+  perModel: z.array(z.object({ model: z.string(), score: z.number() })),
+  competitors: z.array(
+    z.object({
+      name: z.string(),
+      mentions: z.number(),
+      sov: z.number(),
+      isTarget: z.boolean()
+    })
+  ),
+  citations: z.array(
+    z.object({
+      domain: z.string(),
+      count: z.number(),
+      share: z.number(),
+      /** Narrowed to CITATION_BUCKETS (08 section 4.8 change 2): one source for the filter and the OpenAPI enum. */
+      bucket: z.enum(CITATION_BUCKETS)
+    })
+  ),
+  recommendations: z.array(
+    z.object({ title: z.string(), body: z.string(), priority: z.number() })
+  ),
+  methodologyVersion: z.string()
+});
+var siteUrlInput = z.object({ url: z.string().url() }).strict();
+var severityFinding = z.object({
+  severity: z.enum(["error", "warning"]),
+  message: z.string()
+});
+var crawlerAccessResult = z.object({
+  origin: z.string(),
+  robotsStatus: z.number().int(),
+  /** 4xx on robots.txt: everything is allowed. */
+  robotsMissing: z.boolean(),
+  /** 5xx: compliant crawlers treat this as full disallow. */
+  robotsServerError: z.boolean(),
+  truncated: z.boolean(),
+  sitemaps: z.array(z.string()),
+  bots: z.array(
+    z.object({
+      token: z.string(),
+      operator: z.string(),
+      category: z.string(),
+      /** Operator reputation, not a guarantee. robots.txt is voluntary. Never coerce to a boolean. */
+      respectsRobots: z.enum(["yes", "no", "unverified"]),
+      allowed: z.boolean(),
+      via: z.enum(["named", "wildcard", "none"]),
+      matchedLine: z.number().int().nullable(),
+      note: z.string().nullable(),
+      untrusted: z.object({
+        /** The verbatim robots.txt line that decided it. Third-party text, not instructions. */
+        matchedRule: z.string().nullable()
+      })
+    })
+  ),
+  summary: z.object({ allowed: z.number().int(), blocked: z.number().int() })
+});
+var llmsTxtValidation = z.object({
+  origin: z.string(),
+  status: z.number().int(),
+  missing: z.boolean(),
+  score: z.number().int().min(0).max(100).nullable(),
+  findings: z.array(
+    z.object({
+      severity: z.enum(["error", "warning", "info"]),
+      message: z.string(),
+      line: z.number().int().optional()
+    })
+  ),
+  stats: z.object({
+    lines: z.number().int(),
+    bytes: z.number().int(),
+    sections: z.number().int(),
+    entries: z.number().int(),
+    entriesWithDescription: z.number().int()
+  }).nullable(),
+  linksChecked: z.number().int(),
+  brokenLinks: z.array(z.object({ url: z.string(), status: z.number().int() })).max(30),
+  hasLlmsFullTxt: z.boolean()
+});
+var LLMS_TXT_DEPTHS = ["index", "full"];
+var generateLlmsTxtInput = z.object({
+  url: z.string().url(),
+  depth: z.enum(LLMS_TXT_DEPTHS).default("index"),
+  siteName: z.string().max(120).optional(),
+  description: z.string().max(400).optional()
+}).strict();
+var llmsTxtGeneration = z.object({
+  untrusted: z.object({
+    /** The generated file. Untrusted: derived from third-party pages. */
+    content: z.string()
+  }),
+  depth: z.enum(LLMS_TXT_DEPTHS),
+  pageCount: z.number().int(),
+  skippedCount: z.number().int(),
+  discoveredVia: z.enum(["sitemap", "links", "sitemap+links"]),
+  timedOut: z.boolean(),
+  notices: z.array(z.string()),
+  totalWords: z.number().int().optional(),
+  estTokens: z.number().int().optional()
+});
+var sitemapGeneration = z.object({
+  untrusted: z.object({
+    /** The generated sitemap. Untrusted: URLs discovered on a third-party site. */
+    xml: z.string()
+  }),
+  urlCount: z.number().int(),
+  skipped: z.number().int(),
+  discoveredVia: z.enum(["sitemap", "links", "sitemap+links"]),
+  timedOut: z.boolean()
+});
+var chunkAnalysisResult = z.object({
+  url: z.string(),
+  mode: z.enum(["html", "text"]),
+  score: z.number().int().min(0).max(100),
+  errors: z.number().int(),
+  warnings: z.number().int(),
+  strengthCount: z.number().int(),
+  totalWords: z.number().int(),
+  totalTokens: z.number().int(),
+  topFixes: z.array(z.string()).max(5),
+  docFindings: z.array(severityFinding),
+  chunks: z.array(
+    z.object({
+      level: z.number().int().min(0).max(6),
+      untrusted: z.object({
+        /** Third-party page text, not an instruction. */
+        heading: z.string().nullable()
+      }),
+      words: z.number().int(),
+      tokens: z.number().int(),
+      paragraphs: z.number().int(),
+      longestParagraphWords: z.number().int(),
+      findings: z.array(severityFinding),
+      strengths: z.array(z.string())
+    })
+  ).max(150)
+});
+var structuredDataValidation = z.object({
+  url: z.string(),
+  score: z.number().int().min(0).max(100),
+  entityCount: z.number().int(),
+  errors: z.number().int(),
+  warnings: z.number().int(),
+  passes: z.number().int(),
+  microdataCount: z.number().int(),
+  rdfaCount: z.number().int(),
+  blocks: z.array(
+    z.object({
+      index: z.number().int(),
+      syntaxError: z.string().optional(),
+      entities: z.array(
+        z.object({
+          type: z.string(),
+          untrusted: z.object({
+            /** Entity name as published on the page. Data, not instructions. */
+            name: z.string().optional()
+          }),
+          aiNote: z.string().optional(),
+          findings: z.array(
+            z.object({
+              severity: z.enum(["error", "warning", "pass", "info"]),
+              message: z.string()
+            })
+          )
+        })
+      )
+    })
+  ).max(50)
+});
+var checkMetaInput = z.object({
+  url: z.string().url(),
+  /** Optional target keyword to check for presence and position. */
+  keyword: z.string().max(100).optional()
+}).strict();
+var metaCheck = z.object({
+  level: z.enum(["error", "warning", "suggestion", "pass"]),
+  message: z.string()
+});
+var metaAnalysisResult = z.object({
+  url: z.string(),
+  /** Third-party page text. DATA, never instructions. */
+  untrusted: z.object({
+    title: z.string().nullable(),
+    description: z.string().nullable(),
+    ogDescription: z.string().nullable(),
+    firstParagraph: z.string().nullable()
+  }),
+  score: z.number().int().min(0).max(100),
+  chars: z.number().int(),
+  pixels: z.number().int(),
+  desktopCutoff: z.number().int().nullable(),
+  mobileCutoff: z.number().int().nullable(),
+  checks: z.array(metaCheck),
+  openingParagraphChecks: z.array(metaCheck)
+});
+var SITE_ROUTES = {
+  checkCrawlers: "check-crawlers",
+  validateLlmsTxt: "validate-llms-txt",
+  generateLlmsTxt: "generate-llms-txt",
+  generateSitemap: "generate-sitemap",
+  validateStructuredData: "validate-structured-data",
+  checkMeta: "check-meta",
+  analyzeChunks: "analyze-chunks"
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://whereamimentioned.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var SUPPORTED_API_VERSION = API_VERSION;
+var MAX_GET_RETRIES = 2;
+var RETRY_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
+var RETRY_BASE_MS = 500;
+var RETRY_MAX_WAIT_MS = 3e4;
+var ApiError = class extends Error {
+  status;
+  code;
+  requestId;
+  details;
+  retryAfterSeconds;
+  constructor(init) {
+    super(init.message);
+    this.name = "ApiError";
+    this.status = init.status;
+    this.code = init.code;
+    this.requestId = init.requestId;
+    this.details = init.details;
+    this.retryAfterSeconds = init.retryAfterSeconds;
+  }
+};
+var ApiTimeoutError = class extends Error {
+  timeoutMs;
+  method;
+  path;
+  constructor(method, path, timeoutMs) {
+    super(`${method} ${path} timed out after ${timeoutMs} ms`);
+    this.name = "ApiTimeoutError";
+    this.timeoutMs = timeoutMs;
+    this.method = method;
+    this.path = path;
+  }
+};
+function parseRetryAfter(value) {
+  if (value === null) return null;
+  const s = value.trim();
+  if (/^\d+$/.test(s)) return Number(s);
+  const at = Date.parse(s);
+  if (Number.isNaN(at)) return null;
+  return Math.max(0, Math.ceil((at - Date.now()) / 1e3));
+}
+function parseApiVersion(value) {
+  if (value === null) return null;
+  const n = Number(value.trim());
+  return Number.isInteger(n) ? n : null;
+}
+function buildQuery(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      if (value.length > 0) params.set(key, value.join(","));
+      continue;
+    }
+    params.set(key, String(value));
+  }
+  const s = params.toString();
+  return s ? `?${s}` : "";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isAbortError(err) {
+  return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+}
+function seg(value) {
+  return encodeURIComponent(value);
+}
+function createWamClient(opts) {
+  const baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchImpl = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const state = {
+    apiVersion: null,
+    requestId: null,
+    lastResponse: null
+  };
+  function noteHeaders(res) {
+    const v = parseApiVersion(res.headers.get(API_VERSION_HEADER));
+    if (v !== null) state.apiVersion = v;
+    const rid = res.headers.get("X-Request-Id");
+    if (rid) state.requestId = rid;
+    state.lastResponse = {
+      status: res.status,
+      headers: res.headers,
+      replayed: res.headers.get(IDEMPOTENT_REPLAY_HEADER) === "true"
+    };
+  }
+  function nonJsonError(res) {
+    return new ApiError({
+      status: res.status,
+      code: "unknown",
+      message: `Unexpected non-JSON response (HTTP ${res.status})`,
+      requestId: res.headers.get("X-Request-Id"),
+      details: { contentType: res.headers.get("content-type"), bodyPreview: res.text.slice(0, 200) },
+      retryAfterSeconds: parseRetryAfter(res.headers.get("Retry-After"))
+    });
+  }
+  function toApiError(res) {
+    const retryAfterHeader = parseRetryAfter(res.headers.get("Retry-After"));
+    const headerRequestId = res.headers.get("X-Request-Id");
+    const text = res.text;
+    let parsed = void 0;
+    try {
+      parsed = text ? JSON.parse(text) : void 0;
+    } catch {
+      parsed = void 0;
+    }
+    const env = typeof parsed === "object" && parsed !== null && "error" in parsed ? parsed.error : void 0;
+    if (typeof env === "object" && env !== null && typeof env.code === "string") {
+      const e = env;
+      const details = typeof e.details === "object" && e.details !== null && !Array.isArray(e.details) ? e.details : void 0;
+      const detailsRetry = details && typeof details.retryAfterSeconds === "number" ? details.retryAfterSeconds : null;
+      return new ApiError({
+        status: res.status,
+        code: e.code,
+        message: typeof e.message === "string" ? e.message : `HTTP ${res.status}`,
+        requestId: typeof e.requestId === "string" ? e.requestId : headerRequestId,
+        details,
+        retryAfterSeconds: retryAfterHeader ?? detailsRetry
+      });
+    }
+    return nonJsonError(res);
+  }
+  async function attempt(spec, url) {
+    const headers = {
+      Accept: spec.as === "bytes" ? "*/*" : "application/json",
+      "User-Agent": opts.userAgent
+    };
+    if (spec.auth !== false) {
+      headers[API_VERSION_HEADER] = String(API_VERSION);
+      if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
+      const org = spec.org === null ? void 0 : spec.org ?? opts.org;
+      if (org) headers["X-Wam-Org"] = org;
+    }
+    if (spec.idempotencyKey !== void 0) headers["Idempotency-Key"] = spec.idempotencyKey;
+    if (spec.body !== void 0) headers["Content-Type"] = "application/json";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(url, {
+        method: spec.method,
+        headers,
+        body: spec.body === void 0 ? void 0 : JSON.stringify(spec.body),
+        signal: controller.signal,
+        redirect: "manual"
+      });
+      noteHeaders(res);
+      if (res.ok && spec.as === "bytes") {
+        return { status: res.status, ok: true, headers: res.headers, text: "", bytes: await res.arrayBuffer() };
+      }
+      return { status: res.status, ok: res.ok, headers: res.headers, text: await res.text(), bytes: null };
+    } catch (err) {
+      if (isAbortError(err)) throw new ApiTimeoutError(spec.method, spec.path, timeoutMs);
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async function request(spec) {
+    const url = `${baseUrl}${spec.path}${buildQuery(spec.query)}`;
+    const retryable = spec.method === "GET";
+    let attemptNo = 0;
+    state.lastResponse = null;
+    for (; ; ) {
+      let res;
+      try {
+        res = await attempt(spec, url);
+      } catch (err) {
+        if (retryable && attemptNo < MAX_GET_RETRIES && !(err instanceof ApiTimeoutError)) {
+          await sleep(Math.min(RETRY_BASE_MS * 2 ** attemptNo, RETRY_MAX_WAIT_MS));
+          attemptNo += 1;
+          continue;
+        }
+        throw err;
+      }
+      if (res.ok) {
+        if (spec.as === "bytes") return new Uint8Array(res.bytes ?? new ArrayBuffer(0));
+        if (!res.text) return void 0;
+        try {
+          return JSON.parse(res.text);
+        } catch {
+          throw nonJsonError(res);
+        }
+      }
+      if (retryable && attemptNo < MAX_GET_RETRIES && RETRY_STATUSES.has(res.status)) {
+        const retryAfter = parseRetryAfter(res.headers.get("Retry-After"));
+        const backoff = RETRY_BASE_MS * 2 ** attemptNo;
+        const wait = retryAfter !== null ? Math.max(retryAfter * 1e3, backoff) : backoff;
+        await sleep(Math.min(wait, RETRY_MAX_WAIT_MS));
+        attemptNo += 1;
+        continue;
+      }
+      throw toApiError(res);
+    }
+  }
+  const v1 = "/api/v1";
+  const site = async (route, body) => request({ method: "POST", path: `/api/site/${route}`, body, auth: false, org: null });
+  return {
+    get lastApiVersion() {
+      return state.apiVersion;
+    },
+    get lastRequestId() {
+      return state.requestId;
+    },
+    get lastResponse() {
+      return state.lastResponse;
+    },
+    me: () => request({ method: "GET", path: `${v1}/me` }),
+    credits: () => request({ method: "GET", path: `${v1}/credits` }),
+    organizations: {
+      list: (q) => request({ method: "GET", path: `${v1}/organizations`, query: q, org: null }),
+      create: (body, idempotencyKey2) => request({
+        method: "POST",
+        path: `${v1}/organizations`,
+        body,
+        org: null,
+        idempotencyKey: idempotencyKey2
+      })
+    },
+    workspaces: {
+      list: (q) => request({ method: "GET", path: `${v1}/workspaces`, query: q }),
+      get: (slug) => request({ method: "GET", path: `${v1}/workspaces/${seg(slug)}` }),
+      // The org travels as X-Wam-Org, overriding opts.org, and is never put in the body.
+      create: async (orgSlug, body) => {
+        if (typeof orgSlug !== "string" || orgSlug.trim() === "") {
+          throw new TypeError("workspaces.create: orgSlug is required and must not be empty");
+        }
+        return request({ method: "POST", path: `${v1}/workspaces`, body, org: orgSlug });
+      }
+    },
+    scans: {
+      list: (ws, q) => request({ method: "GET", path: `${v1}/workspaces/${seg(ws)}/scans`, query: q }),
+      estimate: (ws) => request({ method: "POST", path: `${v1}/workspaces/${seg(ws)}/scans/estimate`, body: {} }),
+      create: (ws, body, idempotencyKey2) => request({
+        method: "POST",
+        path: `${v1}/workspaces/${seg(ws)}/scans`,
+        body,
+        idempotencyKey: idempotencyKey2
+      }),
+      get: (scanId) => request({ method: "GET", path: `${v1}/scans/${seg(scanId)}` }),
+      answers: (scanId, q) => request({ method: "GET", path: `${v1}/scans/${seg(scanId)}/answers`, query: q }),
+      report: (scanId, format) => format === "json" ? request({ method: "GET", path: `${v1}/scans/${seg(scanId)}/report`, query: { format } }) : request({
+        method: "GET",
+        path: `${v1}/scans/${seg(scanId)}/report`,
+        query: { format },
+        as: "bytes"
+      })
+    },
+    prompts: {
+      list: (ws, q) => request({ method: "GET", path: `${v1}/workspaces/${seg(ws)}/prompts`, query: q }),
+      create: (ws, body) => request({ method: "POST", path: `${v1}/workspaces/${seg(ws)}/prompts`, body }),
+      patch: (ws, promptId, body) => request({
+        method: "PATCH",
+        path: `${v1}/workspaces/${seg(ws)}/prompts/${seg(promptId)}`,
+        body
+      }),
+      remove: async (ws, promptId) => {
+        try {
+          await request({
+            method: "DELETE",
+            path: `${v1}/workspaces/${seg(ws)}/prompts/${seg(promptId)}`
+          });
+        } catch (err) {
+          if (err instanceof ApiError && err.status === 404) return;
+          throw err;
+        }
+      }
+    },
+    competitors: {
+      list: (ws, q) => request({ method: "GET", path: `${v1}/workspaces/${seg(ws)}/competitors`, query: q }),
+      create: (ws, body) => request({ method: "POST", path: `${v1}/workspaces/${seg(ws)}/competitors`, body })
+    },
+    recommendations: {
+      list: (ws, q) => request({
+        method: "GET",
+        path: `${v1}/workspaces/${seg(ws)}/recommendations`,
+        query: q
+      })
+    },
+    citations: {
+      list: (ws, q) => request({ method: "GET", path: `${v1}/workspaces/${seg(ws)}/citations`, query: q })
+    },
+    site: {
+      checkCrawlers: (url) => site(SITE_ROUTES.checkCrawlers, { url }),
+      validateLlmsTxt: (url) => site(SITE_ROUTES.validateLlmsTxt, { url }),
+      generateLlmsTxt: (url, o) => site(SITE_ROUTES.generateLlmsTxt, { url, depth: o?.full ? "full" : "index" }),
+      generateSitemap: (url) => site(SITE_ROUTES.generateSitemap, { url }),
+      validateStructuredData: (url) => site(SITE_ROUTES.validateStructuredData, { url }),
+      checkMeta: (url, keyword) => site(SITE_ROUTES.checkMeta, keyword === void 0 ? { url } : { url, keyword }),
+      analyzeChunks: (url) => site(SITE_ROUTES.analyzeChunks, { url })
+    },
+    keys: {
+      revokeSelf: (all) => request({
+        method: "DELETE",
+        path: `${v1}/keys/self`,
+        query: all === void 0 ? void 0 : { all },
+        org: null
+      })
+    }
+  };
+}
+export {
+  ANSWER_CITATIONS_MAX,
+  ANSWER_TEXT_MAX_CHARS,
+  API_ERROR_CODES,
+  API_ERROR_DETAILS,
+  API_KEY_ENVS,
+  API_KEY_KINDS,
+  API_SCOPES,
+  API_VERSION,
+  API_VERSION_HEADER,
+  ApiError,
+  ApiTimeoutError,
+  CITATION_BUCKETS,
+  DEFAULT_BASE_URL,
+  DEFAULT_TIMEOUT_MS,
+  IDEMPOTENT_REPLAY_HEADER,
+  INTENT_STAGES,
+  LLMS_TXT_DEPTHS,
+  MAX_GET_RETRIES,
+  ORG_ROLES,
+  ORG_TYPES,
+  PROMPT_SOURCES,
+  PROMPT_TYPES,
+  QUOTE_TTL_SECONDS,
+  READ_ONLY_SCOPES,
+  RECOMMENDATION_STATUSES,
+  RECOMMENDATION_TYPES,
+  REPORT_FORMATS,
+  SCAN_MODES,
+  SCAN_STATUSES,
+  SENTIMENTS,
+  SITE_ROUTES,
+  SUPPORTED_API_VERSION,
+  TIERS,
+  answerCitation,
+  answerListQuery,
+  apiErrorBody,
+  brandPresent,
+  checkMetaInput,
+  chunkAnalysisResult,
+  citation,
+  citationListQuery,
+  competitor,
+  conflictDetails,
+  crawlerAccessResult,
+  createCompetitorBody,
+  createOrganizationBody,
+  createOrganizationResult,
+  createPromptBody,
+  createScanBody,
+  createScanResult,
+  createWamClient,
+  createWorkspaceBody,
+  credits,
+  deletePromptResult,
+  estimateScanBody,
+  featureNotAvailableDetails,
+  generateLlmsTxtInput,
+  idempotencyKey,
+  insufficientCreditsDetails,
+  latestScanRef,
+  llmsTxtGeneration,
+  llmsTxtValidation,
+  meResponse,
+  metaAnalysisResult,
+  organizationSummary,
+  page,
+  pageQuery,
+  pagination,
+  parseErrorDetails,
+  patchPromptBody,
+  prompt,
+  promptListQuery,
+  promptListResponse,
+  quotePayload,
+  rateLimitedDetails,
+  recommendation,
+  recommendationListQuery,
+  reportData,
+  reportNotFoundDetails,
+  requestId,
+  revokeSelfQuery,
+  revokeSelfResult,
+  scanAlreadyRunningDetails,
+  scanAnswer,
+  scanEstimate,
+  scanListQuery,
+  scanModelRef,
+  scanProgress,
+  scanStatus,
+  scanSummary,
+  siteUrlInput,
+  sitemapGeneration,
+  structuredDataValidation,
+  validationFailedDetails,
+  workspaceDetail,
+  workspaceSummary
+};