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/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

• consume domain contracts from the contracts repo, do not redefine them
• 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. Publish any updated domain contracts first, including @trafiflow/tss-lib-competitive-intelligence-contracts when Competitive Intelligence schemas changed.
3. Bump version in package.json.
4. Push the commit and create a matching tag such as v0.5.0.
5. 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.5.0: aligns the public Competitive Intelligence SDK with the published contracts package and the new brand-intelligence surfaces

Local workflow

pnpm install
pnpm typecheck
pnpm build

Workflow API

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

• createWorkflow()
• getWorkflow()
• listWorkflowJobs()
• getJob()
• getJobResult()
• listGrowthPlaybooks()

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

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);
}

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

Auth options

The Competitive Intelligence client accepts 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);