@weavix/tracker-core

Shared TypeScript types and a low-level bridge layer for Tracker plugins — slot context types, a typed hostApi, and trigger handler registration.

This package is a base layer used by @weavix/tracker-plugin-sdk and @weavix/tracker-plugin-sdk-react, which re-export everything from this package. If you are building a Tracker plugin, install one of those instead — reach for @weavix/tracker-core directly only if you need the types without the rest of the SDK.

Installation

npm install @weavix/tracker-core @weavix/sdk-core

Quick start

import { hostApi } from '@weavix/tracker-core';
import type { SlotContextMap } from '@weavix/tracker-core';

hostApi.init({ autoResize: true });
await hostApi.notifyReady();

// Typed per slot — for 'issue.action' this resolves to `Issue`
const context = await hostApi.getContext();

Slot contexts

Tracker plugins render into predefined slots — places in the UI such as an issue's action panel, a queue tab, or the navigation menu. Each slot passes a different shape of context data to the plugin, described by SlotContextMap.

import type { SlotContextMap } from '@weavix/tracker-core';

type IssueActionContext = SlotContextMap['issue.action']; // Issue

| Slot | Context type | What it contains | |------|--------------|-------------------| | issue.action, drawer.issue.action, issue.block, drawer.issue.block, issue.tab, drawer.issue.tab, issue.editor.action | Issue | Full issue data | | issue.comment.action | IssueCommentActionSlotContext | The comment the action was triggered from, with its attachments | | queue.action, queue.tab | QueueSlotContext | Queue data | | project.action, project.block, project.tab, project.editor.action | ProjectSlotContext | Project data with progress and board id | | portfolio.action, portfolio.block, portfolio.tab, portfolio.editor.action | PortfolioSlotContext | Portfolio data with progress | | goal.action, goal.block, goal.tab, goal.editor.action | GoalSlotContext | Goal data with progress | | board.tab | BoardTabSlotContext | Board data, including the active sprint if any | | attachment.viewer.action | AttachmentViewerActionSlotContext | The attachment blob and its metadata | | trigger.create.action | TriggerCreateActionsSlotContext | The queue the trigger is being created for | | trigger.edit.action | TriggerEditActionsSlotContext | The queue and the current trigger settings | | navigation | Record<string, never> | No entity context |

TRACKER_SLOTS is the runtime list of slot names, kept in sync with SlotContextMap by a compile-time check; TrackerSlot is the corresponding union type.

import { TRACKER_SLOTS } from '@weavix/tracker-core';
import type { TrackerSlot } from '@weavix/tracker-core';

const isTrackerSlot = (slot: string): slot is TrackerSlot =>
  (TRACKER_SLOTS as readonly string[]).includes(slot);

hostApi

A Tracker-typed wrapper over hostApi from @weavix/sdk-core: getContext() and close() are typed per slot via SlotContextMap and PluginClosePayloadMap. Every other method — lifecycle, theme, language, external APIs — behaves exactly as in @weavix/sdk-core.

import { hostApi } from '@weavix/tracker-core';

hostApi.init({ autoResize: true });
await hostApi.notifyReady();

const theme = await hostApi.getTheme();      // 'light' | 'dark' | ...
const slot = hostApi.getSlot();               // current slot name
const context = await hostApi.getContext();   // SlotContextMap[slot]

await hostApi.close(); // payload type depends on the slot

Editor and viewer slots (issue.editor.action, goal.editor.action, project.editor.action, portfolio.editor.action, attachment.viewer.action) expect a specific payload on close(), describing what the user did in the editor; every other slot closes without a payload. PluginClosePayloadMap and ClosePluginPayload<TSlot> describe these per slot.

For toast notifications, confirmation dialogs, navigation, shared storage, and Tracker Public API calls, use @weavix/tracker-plugin-sdk (or @weavix/sdk-core directly) — this package only covers the Tracker-typed subset above.

Trigger action data

Plugins registered in the trigger.create.action / trigger.edit.action slots configure a webhook trigger and hand its settings back to the host through a getData handler.

import { setHandler } from '@weavix/tracker-core';
import type { TriggerActionData } from '@weavix/tracker-core';

const data: TriggerActionData = {
  url: 'https://example.com/webhook',
  authentication: { type: 'NO_AUTH' },
};

setHandler('getData', () => data);

TriggerActionData describes the webhook URL and its authentication (BasicWebhookAuthContext, OAuth2WebhookAuthContext, NoAuthWebhookAuthContext, and their Vault-backed variants). The host reads the registered handler with getHandler('getData').

Localized strings

Some Tracker fields (for example, custom field names) are returned as a LocalizedString — either a plain string or an object with per-language values. getLocalizedString resolves it for the current language:

import { getLocalizedString } from '@weavix/tracker-core';

const label = getLocalizedString({ ru: 'Задача', en: 'Issue' }, 'en'); // 'Issue'
const plain = getLocalizedString('plain string', 'en');                // 'plain string'

Types

Tracker domain types, re-exported from @weavix/tracker-api-types for convenience:

import type {
  Issue,
  Attachment,
  EntityLink,
  MetaEntityV2,
  Reference,
  UserReferenceV2,
  LocalizedString,
  ObjectId,
  VaultId,
  DateTime,
  Direction,
  Relationship,
  IssueLinkType,
  IssueLinkChainId,
  IssueIndexReference,
  WebhookAuthContext,
  BasicWebhookAuthContext,
  OAuth2WebhookAuthContext,
  NoAuthWebhookAuthContext,
  VaultBasicWebhookAuthContext,
  VaultOAuth2WebhookAuthContext,
  WebhookTriggerActionInput,
  TriggerActionInput,
} from '@weavix/tracker-core';

Slot, close-payload, and handler types:

import type {
  SlotContextMap,
  TrackerSlot,
  ClosePluginPayload,
  PluginClosePayloadMap,
  TriggerActionData,
  GetDataResultMap,
} from '@weavix/tracker-core';

Message, RequestMessage, TrackerContract, and BaseContract describe the low-level postMessage protocol between the host and the plugin iframe. Most plugins never need them directly — they exist for advanced, host-side integrations.

Related packages

| Package | Purpose | |---------|---------| | @weavix/tracker-plugin-sdk | Full Tracker plugin SDK: hostApi, trackerApi, uiApi, storageApi (recommended) | | @weavix/tracker-plugin-sdk-react | React integration: TrackerPluginProvider, hooks | | @weavix/tracker-api-plugin | Typed Tracker Public API client | | @weavix/tracker-api-types | Tracker Public API v3 OpenAPI types | | @weavix/sdk-core | Base plugin runtime |

License

SEE LICENSE IN LICENSE