tss-lib-sdk

Official SDK entrypoint for TSS consumers.

Mission

Make protected TSS services easy to consume from apps, BFFs, Supabase Functions, scripts, and coding agents without forcing teams to manually interpret raw contracts.

Public package

• @trafiflow/tss-sdk
• current surface: @trafiflow/tss-sdk/competitive-intelligence
• current surface: @trafiflow/tss-sdk/funnel-analysis
• current surface: @trafiflow/tss-sdk/social-scraping
• external distribution target: one installable package with no workspace-only runtime dependencies

Consumers

• trafiflow_ux_lab through functions or BFFs
• internal admin tooling
• future TSS-integrated apps and agents

Design rules

• expose high-level client methods instead of leaking raw fetch details
• stay compatible with both Node and Deno/Edge runtimes
• keep the published SDK installable outside the TSS workspace

External distribution

Build and pack the SDK from the workspace:

cd tss-lib-sdk
pnpm pack

That produces a .tgz tarball that an external developer can install directly:

pnpm add ./trafiflow-tss-sdk-0.1.0.tgz

If you publish to a registry later, the same package can be installed with:

pnpm add @trafiflow/tss-sdk

Release

The repo is configured to publish to npmjs as a public package.

1. Set the GitHub Actions secret NPM_TOKEN in the tss-lib-sdk repo.
2. Bump version in package.json.
3. Push the commit and create a matching tag such as v0.6.0.
4. Push the tag.

The publish workflow validates that the tag version matches package.json, runs typecheck/build/pack, and then publishes with provenance.

Current release target:

• 0.8.0: adds the initial Funnel Analysis client surface with a synchronous placeholder analysis endpoint

Local workflow

pnpm install
pnpm typecheck
pnpm build

Workflow API

The Competitive Intelligence SDK now exposes a workflow-oriented API:

• createWorkflow()
• getWorkflow()
• getWorkflowProgress()
• getWorkflowEvents()
• getWorkflowArtifacts()
• listWorkflowJobs()
• getJob()
• getJobResult()
• listGrowthPlaybooks()
• listBrandIntelligenceBrands()
• getBrandBenchmarksLatest()
• getBrandIntelligenceBrand()
• getBrandWorkspaceState()
• updateBrandWorkspaceState()
• getBrandByUrl()
• getBriefingByUrl()
• getGrowthScoreByUrl()
• getWinningProductsByUrl()
• getBrandContextByUrl()
• updateBrandContextByUrl()

createWorkflow() always returns the full jobs[] array so the caller can discover every generated jobId immediately.

Supported workflow types:

• competitive_intelligence
• research_pipeline

Public job types:

• website_structure_analysis
• paid_media_intelligence_analysis
• competitor_landscape_analysis
• landing_page_analysis
• market_taxonomy_classification
• growth_playbook_matching
• growth_score_generation
• market_research_analysis
• creative_effectiveness_analysis
• conversion_funnel_analysis
• briefing_synthesis

New Competitive Intelligence vNext surfaces:

• stage-aware workflow progress including explicit briefing stage
• workflow timeline via persisted events
• persisted workflow artifacts including competitor dossiers/comparisons and briefing outputs
• cached pending/ready briefings/by-url
• normalized pending/ready growth-score/by-url for Growth Score pages, including dataAvailability
• tenant-scoped brand workspace state
• tenant-scoped brand context draft by URL

Minimal usage:

import { createCompetitiveIntelligenceClient } from "@trafiflow/tss-sdk/competitive-intelligence";

const client = createCompetitiveIntelligenceClient({
  baseUrl: process.env.TSS_BASE_URL ?? "https://tss.trafiflow.com",
  authBaseUrl: process.env.TSS_AUTH_BASE_URL,
  tokenProvider: () => process.env.TSS_API_TOKEN,
  apiKeyProvider: () => process.env.TSS_API_KEY,
  tenantScope: {
    tenantId: process.env.TSS_TENANT_ID,
    storeId: process.env.TSS_STORE_ID
  }
});

const workflow = await client.createWorkflow({
  workflowType: "research_pipeline",
  storeUrl: "https://example.com",
  domain: "example.com",
  quizAnswers: {
    category: "apparel"
  }
});

for (const job of workflow.jobs) {
  console.log(job.jobType, job.jobId, job.status);
}

Growth Score by URL:

const growthScore = await client.getGrowthScoreByUrl({
  url: "https://example.com",
  forceRefresh: false
});

if (growthScore.status === "ready") {
  console.log(growthScore.summary.composite, growthScore.dataAvailability.missing);
}

getGrowthScoreByUrl() reuses the Competitive Intelligence briefing flow. Ready responses expose the briefing data in Growth Score-friendly field names and preserve dataAvailability so consumers can render explicit missing-source states for merchant funnel pages, creative assets, agent queue, integrations, discussion threads, and first-party metrics.

Examples

• examples/node-usage.ts
• examples/social-scraping-node-usage.ts
• examples/deno-edge.ts
• examples/claude-code-runner.mjs: copy-ready runner for Claude Code Desktop users

Funnel Analysis API

funnel-analysis exposes a synchronous URL analysis surface. The current service implementation is intentionally a placeholder and always returns a fixed not-implemented analysis string.

The Funnel Analysis client exposes:

• analyzeUrl()

Minimal usage:

import { createFunnelAnalysisClient } from "@trafiflow/tss-sdk/funnel-analysis";

const client = createFunnelAnalysisClient({
  baseUrl: process.env.TSS_BASE_URL ?? "https://tss.trafiflow.com",
  authBaseUrl: process.env.TSS_AUTH_BASE_URL,
  tokenProvider: () => process.env.TSS_API_TOKEN,
  apiKeyProvider: () => process.env.TSS_API_KEY,
  tenantScope: {
    tenantId: process.env.TSS_TENANT_ID,
    storeId: process.env.TSS_STORE_ID
  }
});

const result = await client.analyzeUrl({
  url: "https://example.com"
});

console.log(result.analysisText);

Auth options

TSS service clients accept either:

• tokenProvider: when the caller already has a short-lived JWT bearer token
• apiKeyProvider: when the caller stores a stable TSS_API_KEY and wants the SDK to exchange it for a short-lived JWT automatically through the platform auth service
• authBaseUrl: optional override for the auth host; defaults to the same host as baseUrl and exchanges via /api/v1/auth/token

If both are provided, the SDK prefers tokenProvider when it returns a token and falls back to apiKeyProvider otherwise.

Social Scraping API

social-scraping is a separate capability from competitive-intelligence.

• competitive-intelligence may consume assets returned by social scraping
• but scraping, asset access, and asset metadata belong to social-scraping

The Social Scraping client exposes:

• createCollection()
• getCollection()
• getCollectionResult()
• getAsset()
• getAssetMetadata()
• requestAssetAccess()

Minimal usage:

import { TssError } from "@trafiflow/tss-sdk";
import { createSocialScrapingClient } from "@trafiflow/tss-sdk/social-scraping";

const client = createSocialScrapingClient({
  baseUrl: process.env.TSS_BASE_URL ?? "https://tss.trafiflow.com",
  authBaseUrl: process.env.TSS_AUTH_BASE_URL,
  tokenProvider: () => process.env.TSS_API_TOKEN,
  apiKeyProvider: () => process.env.TSS_API_KEY,
  tenantScope: {
    tenantId: process.env.TSS_TENANT_ID,
    storeId: process.env.TSS_STORE_ID
  }
});

const collection = await client.createCollection({
  connector: "tiktok_organic",
  criteria: {
    url: "https://www.tiktok.com/@thirdlove",
    sortBy: "recent"
  },
  limit: 3,
  downloadPolicy: "metadata_and_assets"
});

let result;
while (true) {
  try {
    result = await client.getCollectionResult(collection.jobId);
    break;
  } catch (error) {
    if (error instanceof TssError && error.status === 409) {
      await new Promise((resolve) => setTimeout(resolve, 2500));
      continue;
    }
    throw error;
  }
}

const access = await client.requestAssetAccess(result.assets[0].assetId);
console.log(access.downloadUrl);