SDK Reference

Yapture’s parser and type definitions are published as standalone packages. They have zero runtime dependencies, work in the browser and on the server, and are the same code that ships in every Yapture client.

Package	Purpose	Size (gz)
@yapture/nlp	Script parser, renderer, badge separator.	~6 KB
@yapture/types	TypeScript type definitions for Yap, List, ParsedData, etc.	0 KB (types-only)

Install with your package manager of choice:

bun add @yapture/nlp @yapture/types
# or
npm install @yapture/nlp @yapture/types
# or
pnpm add @yapture/nlp @yapture/types

---

@yapture/nlp

The parser. Three top-level entry points: parse, render, separateBadges.

YaptureNLP.parse(text)

Returns a structured ParsedData object.

import { YaptureNLP } from '@yapture/nlp';

const parsed = YaptureNLP.parse(
  'Fix login bug #!high #+alice #@backend due:2026-04-01'
);

// {
//   priority: 'HIGH',
//   assignees: ['alice'],
//   workspaces: ['backend'],
//   tags: [],
//   goals: [],
//   actions: [],
//   dueDate: Date('2026-04-01'),
//   isRecurring: false,
//   metadata: {},
//   cleanText: 'Fix login bug',
// }

YaptureNLP.render(text)

Returns an array of RenderedTextPart objects suitable for rendering colored badges in any UI framework. Each part is { type: 'text' | 'badge', text, badgeType?, value? }.

const parts = YaptureNLP.render('Deploy succeeded #!low #@ops');

// [
//   { type: 'text', text: 'Deploy succeeded ' },
//   { type: 'badge', badgeType: 'priority', value: 'LOW', text: '#!low' },
//   { type: 'text', text: ' ' },
//   { type: 'badge', badgeType: 'workspace', value: 'ops', text: '#@ops' },
// ]

Use this with the canonical script-colors.ts palette (vendored at src/lib/script-colors.ts) to render badges that exactly match the production app.

YaptureNLP.separateBadges(text)

Splits the input into clean text and a separate badge list. Useful for “as it’d appear in the app” previews where the prefix tokens are rendered separately from the prose.

const { cleanText, badges } = YaptureNLP.separateBadges(
  'Sprint 42 Tasks: prep slides #@work:design'
);

// cleanText: 'Sprint 42 Tasks: prep slides'
// badges: [{ type: 'workspace', value: 'work:design', raw: '#@work:design' }]

---

@yapture/types

The canonical TypeScript types. Import these in any TypeScript project that touches Yapture data.

import type { Yap, List, ParsedData, Role, Priority } from '@yapture/types';

const yap: Yap = {
  id: 'yap_01HX...',
  text: 'Fix login bug #!high',
  parsed: { priority: 'HIGH', /* ... */ } satisfies ParsedData,
  status: 'open',
  createdAt: new Date(),
};

const list: List = {
  ref: 'groc-7k2x',
  kind: 'tasks',
  title: 'agent inbox',
  createdAt: new Date(),
  docVersion: 0,
};

const role: Role = 'editor'; // 'owner' | 'editor' | 'agent' | 'viewer'
const priority: Priority = 'URGENT'; // 'URGENT' | 'HIGH' | 'MEDIUM' | 'LOW'

The types ship as .d.ts only — there’s no runtime cost.

---

React rendering example

The marketing site renders script badges with this minimal React component, sharing the canonical palette:

import { YaptureNLP } from '@yapture/nlp';
import { getBadgeColors } from '~/lib/script-colors';

export function TaskBadges({ text }: { text: string }) {
  const parts = YaptureNLP.render(text);
  return (
    <span>
      {parts.map((part, i) => {
        if (part.type === 'text') return <span key={i}>{part.text}</span>;
        const colors = getBadgeColors(part.badgeType, part.value);
        return (
          <span
            key={i}
            className="inline-flex rounded-full px-2 py-0.5 text-xs font-medium"
            style={{
              background: colors.darkBg,
              color: colors.darkText,
              border: `1px solid ${colors.border}`,
            }}
          >
            {part.text}
          </span>
        );
      })}
    </span>
  );
}

For SolidJS or Vue ports, mirror this structure — the parser output is framework-agnostic.

---

Stability

@yapture/nlp and @yapture/types follow semver. The parser output schema is locked at v1.x — adding new fields is a minor bump, removing or changing existing fields is a major bump.

The script-colors.ts palette is not part of the published packages — it’s vendored from app_v2/src/lib/dsl-colors.ts (upstream filename) so that the marketing site, the production app, and any third-party UI can keep their badge colors in sync.