@toznysecure/teambots-sdk

TypeScript client and integration contract for partner apps (Currents, DotClinic, …).

Plan: docs/plans/integration-sdk-hardening-plan.md
API reference: docs/sdk/INTEGRATION_SDK.md

Install

cd sdk && npm install && npm run build

Monorepo consumer:

{ "dependencies": { "@toznysecure/teambots-sdk": "file:../sdk" } }

Quick start

import {
  TeamBotsClient,
  CURRENTS_SKILL_CAPABILITY_MAP,
  buildCapabilitiesFromManifest,
  buildPartnerAppContext,
  validateToolIntent,
} from '@toznysecure/teambots-sdk';

const client = new TeamBotsClient({
  baseUrl: 'https://api.teambots.ai/api',
  integrationKey: process.env.TEAMBOTS_INTEGRATION_KEY!,
  appId: 'currents',
});

const { manifest } = await client.connectAgent({
  agentEmail: '[email protected]',
  appTenantId: companyUuid,
  adminEmail: '[email protected]',
});

const capabilities = buildCapabilitiesFromManifest(manifest, CURRENTS_SKILL_CAPABILITY_MAP);

await client.registerManifestWebhook({
  appTenantId: companyUuid,
  webhookUrl: 'https://app.example.com/webhooks/teambots/manifest-updated',
});

const reply = await client.channelChat({
  agentId: manifest.agentId,
  appTenantId: companyUuid,
  messages: [{ role: 'user', content: 'Create a task for sprint review' }],
  appContext: buildPartnerAppContext({
    appName: 'Currents',
    manifestSkills: manifest.skills,
    skillCapabilityMap: CURRENTS_SKILL_CAPABILITY_MAP,
  }),
});

for (const intent of reply.toolIntents) {
  const check = validateToolIntent(intent, manifest, CURRENTS_SKILL_CAPABILITY_MAP, capabilities);
  if (!check.valid) continue;
  // dispatch locally…
  await client.reportToolExecution({
    agentId: manifest.agentId,
    appTenantId: companyUuid,
    skillId: intent.skillId,
    action: intent.action,
    success: true,
  });
}

Exports

| Export | Purpose | |--------|---------| | TeamBotsClient | HTTP client (connect, manifest, chat, audit, webhook) | | CURRENTS_SKILL_CAPABILITY_MAP | Canonical 30-skill map — do not copy | | buildCapabilitiesFromManifest | Replace-all capability mirror | | validateToolIntent | Governance gate before local execute | | buildPartnerAppContext | Required appContext.partner payload | | currentsWake / isCurrentsWakeEventEnabled | Currents wake-event contract for task/review/mention/due-date events | | getIntentSchema / validateIntentData | Intent data schemas | | INTEGRATION_ERRORS | Error catalog + remediation |

Version

Package version 0.2.1 — echoed on IntegrationManifest.sdkVersion from TeamBots API.

Publishing to npm

Important: npm publish uploads to npm only. It does not create a GitHub tag. Tags are created with git tag and appear on GitHub only after git push origin vX.Y.Z.

After setup, the normal flow is: create tag → push tag → GitHub Actions publishes to npm.

One-time setup

1. npm org for @toznysecure scope
   Log in at npmjs.com. Your account must be a member of the @toznysecure org with publish access.

2. Create an npm automation token

   • npm → Account → Access Tokens → Generate New Token
   • Type: Automation (for CI; does not expire on 2FA session)
   • Copy the token once — you will not see it again.

3. Add the token to GitHub

   • Repo → Settings → Secrets and variables → Actions
   • New repository secret
   • Name: NPM_TOKEN
   • Value: paste the npm automation token

4. First publish (one time, from your machine) — only if @toznysecure/teambots-sdk does not exist on npm yet:

   npm login
   npm ci && npm run build
   npm publish --access public

5. One-time fix — add the GitHub tag after manual publish
   If you already ran npm publish but GitHub has no tag, run this once for that version (e.g. 0.2.0):

   # From repo root, on the commit that matches what you published
   git tag -a v0.2.0 -m "Release v0.2.0"
   git push origin main
   git push origin v0.2.0

   Check on GitHub: Code → tag dropdown, or Releases / Tags → v0.2.0.

   After this one-time fix, use the automatic flow below for all future releases.

Every release (automatic — recommended)

# From repo root
chmod +x scripts/release.sh
./scripts/release.sh 0.2.1

git push origin main
git push origin v0.2.1

What happens:

1. release.sh updates package.json and src/version.ts to the same version.
2. It commits and creates the git tag locally (e.g. v0.2.1).
3. git push origin v0.2.1 sends the tag to GitHub (tag appears under Tags).
4. Pushing the tag triggers .github/workflows/publish.yml.
5. GitHub Actions builds the SDK and runs npm publish using NPM_TOKEN.

Manual tag only (without release.sh) — if versions are already bumped and committed:

git tag -a v0.2.1 -m "Release v0.2.1"
git push origin main
git push origin v0.2.1

Install in other repos:

npm install @toznysecure/teambots-sdk@^0.2.1

Rules

• Tag must match package.json: tag v0.2.1 → version 0.2.1.
• src/version.ts SDK_VERSION must match package.json (CI checks this).
• Never re-publish the same version to npm — bump the version for every release.
• Prefer push tag → CI publishes over local npm publish, so GitHub and npm stay in sync.