@burdenoff/planmagnet-fe-sdk 2026.703.1

package/dist/index.d.ts

@@ -0,0 +1,840 @@
+import * as react from 'react';
+import { ReactNode, HTMLAttributes } from 'react';
+import { ApolloClient } from '@apollo/client/core';
+import * as graphql from 'graphql';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+import { ClassValue } from 'clsx';
+
+/**
+ * Domain types for the PlanMagnet task SDK.
+ *
+ * These mirror the wspace-planmagnet-svc schema (WorkItem / Project) but are
+ * kept hand-written for Phase 1 so the SDK compiles without a live `schema:pull`.
+ * Phase 2 should replace the hand-written slices with codegen output.
+ */
+/** Board columns (WorkItemStatus). Logical UI order, not schema alpha order. */
+type TaskStatus = "BACKLOG" | "TODO" | "IN_PROGRESS" | "IN_REVIEW" | "TESTING" | "DONE" | "CANCELLED";
+/** Work-item type (WorkItemType). */
+type TaskType = "TASK" | "STORY" | "BUG" | "EPIC" | "SUB_TASK";
+/** Work-item priority (WorkItemPriority). */
+type TaskPriority = "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+/** Cross-product entity link relation (WorkItemLinkRelation). */
+type WorkItemLinkRelation = "RELATED_TO" | "BLOCKS" | "AFFECTS" | "INSPECTS" | "PRODUCES" | "WORKS_ON";
+/**
+ * A work item as rendered on the board — the summary field set from
+ * `WorkItemSummaryFields`.
+ */
+interface Task {
+    id: string;
+    key: string;
+    title: string;
+    type: TaskType;
+    status: TaskStatus;
+    priority: TaskPriority;
+    assigneeId?: string | null;
+    sprintId?: string | null;
+    storyPoints?: number | null;
+    dueDate?: string | null;
+    labels: string[];
+}
+/**
+ * A work item with the full field set from `WorkItemFields` — used by the
+ * detail view (view + inline edit). Superset of `Task` (the board summary).
+ */
+interface WorkItemDetail {
+    id: string;
+    workspaceId: string;
+    projectId: string;
+    key: string;
+    title: string;
+    description?: string | null;
+    type: TaskType;
+    status: TaskStatus;
+    priority: TaskPriority;
+    assigneeId?: string | null;
+    reporterId?: string | null;
+    parentId?: string | null;
+    sprintId?: string | null;
+    storyPoints?: number | null;
+    estimateMinutes?: number | null;
+    timeSpentMinutes?: number | null;
+    dueDate?: string | null;
+    labels: string[];
+    tags: string[];
+    sortOrder?: number | null;
+    metadata?: unknown;
+    createdBy?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    updatedBy?: string | null;
+    deletedAt?: string | null;
+}
+/** Project summary (for the create form's project selector / board scoping). */
+interface Project {
+    id: string;
+    name: string;
+    key: string;
+    status: string;
+    methodology: string;
+    ownerId: string;
+    startDate?: string | null;
+    endDate?: string | null;
+    tags: string[];
+}
+/** Input for `planmagnetCreateWorkItem`. projectId + title + type are required. */
+interface CreateTaskInput {
+    projectId: string;
+    title: string;
+    type: TaskType;
+    description?: string;
+    status?: TaskStatus;
+    priority?: TaskPriority;
+    assigneeId?: string;
+    reporterId?: string;
+    parentId?: string;
+    sprintId?: string;
+    storyPoints?: number;
+    estimateMinutes?: number;
+    dueDate?: string;
+    labels?: string[];
+    tags?: string[];
+    sortOrder?: number;
+}
+/** Input for `planmagnetUpdateWorkItem`. */
+interface UpdateTaskInput {
+    title?: string;
+    description?: string;
+    type?: TaskType;
+    status?: TaskStatus;
+    priority?: TaskPriority;
+    assigneeId?: string;
+    sprintId?: string;
+    storyPoints?: number;
+    dueDate?: string;
+    labels?: string[];
+    tags?: string[];
+    sortOrder?: number;
+}
+/** Filter for `planmagnetWorkItems`. */
+interface ListTasksInput {
+    assigneeId?: string;
+    parentId?: string;
+    priority?: TaskPriority;
+    projectId?: string;
+    reporterId?: string;
+    search?: string;
+    sprintId?: string;
+    status?: TaskStatus;
+    type?: TaskType;
+}
+/** Cursor pagination input (PlanmagnetPaginationInput / PaginationInput). */
+interface TaskPaginationInput {
+    after?: string;
+    before?: string;
+    first?: number;
+    last?: number;
+}
+interface TaskPageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor?: string | null;
+    endCursor?: string | null;
+    totalCount: number;
+}
+/** Shape returned by the ListWorkItems query. */
+interface WorkItemList {
+    items: Task[];
+    pageInfo: TaskPageInfo;
+    totalCount: number;
+}
+/** Shape returned by the GetProjects query. */
+interface ProjectList {
+    items: Project[];
+    pageInfo: TaskPageInfo;
+    totalCount: number;
+}
+/** Board column definition. */
+interface BoardColumn {
+    status: TaskStatus;
+    label: string;
+}
+/**
+ * The default, ordered board columns. Product-agnostic — no farm semantics.
+ * TESTING/CANCELLED are omitted from the default board but are valid statuses;
+ * callers can override via TaskBoardCoreProps.columns.
+ */
+declare const DEFAULT_BOARD_COLUMNS: BoardColumn[];
+/** Priority filter options (UI order). */
+declare const TASK_PRIORITIES: TaskPriority[];
+/** Type filter options (UI order). */
+declare const TASK_TYPES: TaskType[];
+/** All work-item statuses (UI/logical order). */
+declare const TASK_STATUSES: TaskStatus[];
+/**
+ * Human-readable label for an enum value: lower-cases and turns `_` into a
+ * space (e.g. `IN_PROGRESS` → `in progress`, `SUB_TASK` → `sub task`). The UI
+ * capitalizes visually via CSS, so this stays product-agnostic.
+ */
+declare function enumLabel(value: string): string;
+
+interface TaskBoardCoreProps {
+    /** Scope the board to one project (client-side filter for Phase 1). */
+    projectId?: string;
+    /** Board columns to render (defaults to DEFAULT_BOARD_COLUMNS). */
+    columns?: BoardColumn[];
+    /** Read-only mode — hides interactive affordances (no create/drag in Phase 1 either way). */
+    readonly?: boolean;
+    /** Hide the board header (title + count). */
+    hideHeader?: boolean;
+    /** Hide the priority/type filter bar. */
+    hideFilters?: boolean;
+    /**
+     * Field names to hide on each task card. Product-agnostic hook so hosts can
+     * suppress fields that don't apply. Supported: 'key' | 'priority' | 'type' |
+     * 'labels' | 'storyPoints' | 'assignee' | 'dueDate'.
+     */
+    hiddenFields?: string[];
+    /** Called when a task card is clicked. */
+    onTaskClick?: (task: Task) => void;
+    /** Extra classes on the root container. */
+    className?: string;
+    /**
+     * Optional explicit workspace ID. Falls back to the PlanMagnetProvider context.
+     * At least one must be present or the query is skipped.
+     */
+    workspaceId?: string;
+}
+/**
+ * TaskBoardCore — provider-less, prop-driven, product-agnostic Kanban board.
+ *
+ * - Reads Apollo via the ambient `<ApolloProvider>` (BYO). It never creates a
+ *   client and never assumes a router.
+ * - `workspaceId` comes from a prop or the PlanMagnetProvider context.
+ * - Read-only in Phase 1 (no drag/create). Farm-free: no Field/Crop logic.
+ */
+declare function TaskBoardCore({ projectId, columns, readonly: _readonly, hideHeader, hideFilters, hiddenFields, onTaskClick, className, workspaceId: workspaceIdProp, }: TaskBoardCoreProps): react.JSX.Element;
+
+interface TaskBoardProps extends TaskBoardCoreProps {
+    /** Workspace API gateway URL (URL mode). */
+    apiGatewayUrl?: string;
+    /** Platform identity token. */
+    authToken?: string;
+    /** Workspace access token (X-Workspace-Authorization). */
+    workspaceToken?: string;
+    /** Workspace ID. Required. */
+    workspaceId: string;
+    /** Tenant ID. */
+    tenantId?: string;
+    /** Organization ID. */
+    organizationId?: string;
+    /** Optional host allowlist for embedded deployments. */
+    trustedOrigins?: string[];
+    /** Called on UNAUTHENTICATED / FORBIDDEN. */
+    onAuthError?: () => void;
+    /** BYO: provide your own already-authed workspace Apollo client. */
+    workspaceClient?: ApolloClient;
+}
+/**
+ * TaskBoard — standalone, embeddable, product-agnostic task board.
+ *
+ * Thin wrapper that self-provisions (or accepts) an Apollo client via
+ * PlanMagnetProvider, then renders TaskBoardCore. Mirrors the FluidGrids
+ * `WorkflowBuilder` (standalone) → `WorkflowBuilderCore` (BYO) split.
+ *
+ * Two mount modes:
+ *  - URL mode:  <TaskBoard apiGatewayUrl={..} authToken={..} workspaceId={..} />
+ *  - BYO mode:  <TaskBoard workspaceClient={hostClient} workspaceId={..} />
+ *
+ * @example URL mode
+ * ```tsx
+ * <TaskBoard
+ *   apiGatewayUrl="https://graphqlworkspaces.burdenoff.com"
+ *   authToken={token}
+ *   workspaceId="ws-123"
+ *   onTaskClick={(t) => console.log(t)}
+ * />
+ * ```
+ *
+ * @example BYO client (host shell injects its authed client)
+ * ```tsx
+ * <TaskBoard workspaceClient={hostClient} workspaceId="ws-123" readonly />
+ * ```
+ */
+declare function TaskBoard({ apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, organizationId, trustedOrigins, onAuthError, workspaceClient, ...coreProps }: TaskBoardProps): react.JSX.Element;
+
+/**
+ * Supported hideable field keys for the create form. Product-agnostic hook so
+ * hosts can suppress fields that don't apply to their domain.
+ */
+type CreateTaskField = "description" | "type" | "status" | "priority" | "assignee" | "dueDate" | "labels" | "storyPoints";
+interface CreateTaskCoreProps {
+    /**
+     * Project the new work item belongs to. `projectId` is REQUIRED by the
+     * backend (`PlanmagnetCreateWorkItemInput.projectId`). The form blocks submit
+     * until a project id is present.
+     */
+    projectId?: string;
+    /** Field names to hide on the form. */
+    hiddenFields?: CreateTaskField[];
+    /** Default values applied on first render. */
+    defaultValues?: Partial<CreateTaskInput>;
+    /** Hide the form header (title + subtitle). */
+    hideHeader?: boolean;
+    /** Custom submit-button label. */
+    submitLabel?: string;
+    /** Called with the created work item on success. */
+    onCreated?: (workItem: WorkItemDetail) => void;
+    /** Called when the create mutation errors. */
+    onError?: (error: Error) => void;
+    /** Called when the cancel button is pressed (button only shown if provided). */
+    onCancel?: () => void;
+    /** Extra classes on the root container. */
+    className?: string;
+    /** Explicit workspace ID. Falls back to PlanMagnetProvider context. */
+    workspaceId?: string;
+}
+/**
+ * CreateTaskCore — provider-less, prop-driven controlled form that creates a
+ * WorkItem via `planmagnetCreateWorkItem`. BYO-Apollo (reads the ambient
+ * ApolloProvider), semantic-token styled, farm-free.
+ *
+ * Mirrors the TaskBoardCore contract: `workspaceId` from a prop or the
+ * PlanMagnetProvider context, `hiddenFields` for host-driven field suppression.
+ */
+declare function CreateTaskCore({ projectId: projectIdProp, hiddenFields, defaultValues, hideHeader, submitLabel, onCreated, onError, onCancel, className, workspaceId: workspaceIdProp, }: CreateTaskCoreProps): react.JSX.Element;
+
+interface CreateTaskProps extends CreateTaskCoreProps {
+    /** Workspace API gateway URL (URL mode). */
+    apiGatewayUrl?: string;
+    /** Platform identity token. */
+    authToken?: string;
+    /** Workspace access token (X-Workspace-Authorization). */
+    workspaceToken?: string;
+    /** Workspace ID. Required. */
+    workspaceId: string;
+    /** Tenant ID. */
+    tenantId?: string;
+    /** Organization ID. */
+    organizationId?: string;
+    /** Optional host allowlist for embedded deployments. */
+    trustedOrigins?: string[];
+    /** Called on UNAUTHENTICATED / FORBIDDEN. */
+    onAuthError?: () => void;
+    /** BYO: provide your own already-authed workspace Apollo client. */
+    workspaceClient?: ApolloClient;
+}
+/**
+ * CreateTask — standalone, embeddable work-item create form.
+ *
+ * Thin wrapper that self-provisions (or accepts) an Apollo client via
+ * PlanMagnetProvider, then renders CreateTaskCore. Mirrors the
+ * TaskBoard → TaskBoardCore split.
+ *
+ * @example URL mode
+ * ```tsx
+ * <CreateTask
+ *   apiGatewayUrl="https://graphqlworkspaces.burdenoff.com"
+ *   authToken={token}
+ *   workspaceId="ws-123"
+ *   projectId="proj-1"
+ *   onCreated={(wi) => console.log(wi)}
+ * />
+ * ```
+ *
+ * @example BYO client
+ * ```tsx
+ * <CreateTask workspaceClient={hostClient} workspaceId="ws-123" projectId="proj-1" />
+ * ```
+ */
+declare function CreateTask({ apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, organizationId, trustedOrigins, onAuthError, workspaceClient, ...coreProps }: CreateTaskProps): react.JSX.Element;
+
+/** Columns available in the compact list. */
+type TaskListColumn = "key" | "title" | "type" | "status" | "priority" | "assignee" | "dueDate" | "storyPoints" | "labels";
+/** Sort keys for the list. */
+type TaskListSort = "priority" | "status" | "title" | "type" | "dueDate" | "storyPoints";
+interface TaskListCoreProps {
+    /** Scope to one project (server-side filter). */
+    projectId?: string;
+    /** Filter by status. */
+    status?: TaskStatus;
+    /** Filter by type. */
+    type?: TaskType;
+    /** Filter by priority. */
+    priority?: TaskPriority;
+    /** Filter by assignee actor id. */
+    assigneeId?: string;
+    /** Free-text search (server-side). */
+    search?: string;
+    /** Columns to render (order preserved). */
+    columns?: TaskListColumn[];
+    /** Sort key (client-side). */
+    sortBy?: TaskListSort;
+    /** Sort direction. Defaults to ascending. */
+    sortDir?: "asc" | "desc";
+    /** Hide the header (title + count). */
+    hideHeader?: boolean;
+    /** Called with the work-item id when a row is clicked. */
+    onSelect?: (id: string) => void;
+    /** Max items to fetch (pagination.first). Defaults to 200. */
+    limit?: number;
+    /** Extra classes on the root container. */
+    className?: string;
+    /** Explicit workspace ID. Falls back to PlanMagnetProvider context. */
+    workspaceId?: string;
+}
+/**
+ * TaskListCore — provider-less, prop-driven compact list/table of work items.
+ *
+ * Same data source as TaskBoardCore (`LIST_WORK_ITEMS`) but a dense table
+ * layout instead of a kanban. Filters map to the server-side `WorkItemFilter`;
+ * sort is applied client-side. BYO-Apollo, semantic-token only, farm-free.
+ */
+declare function TaskListCore({ projectId, status, type, priority, assigneeId, search, columns, sortBy, sortDir, hideHeader, onSelect, limit, className, workspaceId: workspaceIdProp, }: TaskListCoreProps): react.JSX.Element;
+
+interface TaskListProps extends TaskListCoreProps {
+    /** Workspace API gateway URL (URL mode). */
+    apiGatewayUrl?: string;
+    /** Platform identity token. */
+    authToken?: string;
+    /** Workspace access token (X-Workspace-Authorization). */
+    workspaceToken?: string;
+    /** Workspace ID. Required. */
+    workspaceId: string;
+    /** Tenant ID. */
+    tenantId?: string;
+    /** Organization ID. */
+    organizationId?: string;
+    /** Optional host allowlist for embedded deployments. */
+    trustedOrigins?: string[];
+    /** Called on UNAUTHENTICATED / FORBIDDEN. */
+    onAuthError?: () => void;
+    /** BYO: provide your own already-authed workspace Apollo client. */
+    workspaceClient?: ApolloClient;
+}
+/**
+ * TaskList — standalone, embeddable compact list/table of work items.
+ *
+ * Thin wrapper that self-provisions (or accepts) an Apollo client via
+ * PlanMagnetProvider, then renders TaskListCore. Mirrors the
+ * TaskBoard → TaskBoardCore split.
+ *
+ * @example
+ * ```tsx
+ * <TaskList
+ *   workspaceClient={hostClient}
+ *   workspaceId="ws-123"
+ *   sortBy="priority"
+ *   onSelect={(id) => openTask(id)}
+ * />
+ * ```
+ */
+declare function TaskList({ apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, organizationId, trustedOrigins, onAuthError, workspaceClient, ...coreProps }: TaskListProps): react.JSX.Element;
+
+/** Fields that can be hidden / suppressed on the detail view + edit form. */
+type TaskDetailField = "description" | "type" | "status" | "priority" | "assignee" | "dueDate" | "labels" | "storyPoints";
+interface TaskDetailCoreProps {
+    /** Work-item id to fetch + edit. Required. */
+    id: string;
+    /** Start in read-only mode with no edit affordance. */
+    readonly?: boolean;
+    /** Field names to hide. */
+    hiddenFields?: TaskDetailField[];
+    /** Hide the header (key + title). */
+    hideHeader?: boolean;
+    /** Called with the updated work item after a successful save. */
+    onUpdated?: (workItem: WorkItemDetail) => void;
+    /** Called when the update mutation errors. */
+    onError?: (error: Error) => void;
+    /** Extra classes on the root container. */
+    className?: string;
+}
+/**
+ * TaskDetailCore — provider-less, prop-driven single work-item view with inline
+ * edit. Fetches via `planmagnetWorkItem(id)`, saves via
+ * `planmagnetUpdateWorkItem`. BYO-Apollo, semantic-token only, farm-free.
+ */
+declare function TaskDetailCore({ id, readonly, hiddenFields, hideHeader, onUpdated, onError, className, }: TaskDetailCoreProps): react.JSX.Element;
+
+interface TaskDetailProps extends TaskDetailCoreProps {
+    /** Workspace API gateway URL (URL mode). */
+    apiGatewayUrl?: string;
+    /** Platform identity token. */
+    authToken?: string;
+    /** Workspace access token (X-Workspace-Authorization). */
+    workspaceToken?: string;
+    /** Workspace ID. Required (scopes the client headers). */
+    workspaceId: string;
+    /** Tenant ID. */
+    tenantId?: string;
+    /** Organization ID. */
+    organizationId?: string;
+    /** Optional host allowlist for embedded deployments. */
+    trustedOrigins?: string[];
+    /** Called on UNAUTHENTICATED / FORBIDDEN. */
+    onAuthError?: () => void;
+    /** BYO: provide your own already-authed workspace Apollo client. */
+    workspaceClient?: ApolloClient;
+}
+/**
+ * TaskDetail — standalone, embeddable single work-item view with inline edit.
+ *
+ * Thin wrapper that self-provisions (or accepts) an Apollo client via
+ * PlanMagnetProvider, then renders TaskDetailCore. Mirrors the
+ * TaskBoard → TaskBoardCore split.
+ *
+ * @example
+ * ```tsx
+ * <TaskDetail
+ *   workspaceClient={hostClient}
+ *   workspaceId="ws-123"
+ *   id="wi-1"
+ *   onUpdated={(wi) => console.log(wi)}
+ * />
+ * ```
+ */
+declare function TaskDetail({ apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, organizationId, trustedOrigins, onAuthError, workspaceClient, ...coreProps }: TaskDetailProps): react.JSX.Element;
+
+/**
+ * Which SDK fields the composed page should suppress. The union of the create
+ * form fields and the detail fields — the page fans a single `hiddenFields`
+ * prop out to the board, create form, and detail view so hosts configure the
+ * whole experience in one place.
+ */
+type TasksPageField = CreateTaskField | TaskDetailField;
+/** Payload passed to `onTaskSaved` when a create/update completes. */
+interface TasksPageSaved {
+    workItem: WorkItemDetail;
+    operation: "created" | "updated";
+}
+interface TasksPageCoreProps {
+    /**
+     * Explicit workspace ID. Falls back to the PlanMagnetProvider context. At
+     * least one must be present or the board query is skipped.
+     */
+    workspaceId?: string;
+    /**
+     * Project the "New task" flow creates work items in. REQUIRED for create —
+     * the backend `PlanmagnetCreateWorkItemInput.projectId` is non-null. When
+     * omitted the board still renders read-only-ish (create is disabled).
+     */
+    projectId?: string;
+    /** Scope the board to a single project (client-side filter). */
+    boardProjectId?: string;
+    /** Board columns to render (defaults to DEFAULT_BOARD_COLUMNS). */
+    columns?: BoardColumn[];
+    /** Read-only — hides the "New task" button and disables detail editing. */
+    readonly?: boolean;
+    /**
+     * Field names to hide across the board cards, create form, and detail view.
+     * A product-agnostic hook so hosts can suppress fields that don't apply.
+     */
+    hiddenFields?: TasksPageField[];
+    /** Hide the board's priority/type filter bar. */
+    hideFilters?: boolean;
+    /**
+     * Header/title slot. Pass a string for the default heading, or any node to
+     * fully own the header area. Omit for no header.
+     */
+    header?: ReactNode;
+    /** Called after a successful create OR update (board is refetched first). */
+    onTaskSaved?: (saved: TasksPageSaved) => void;
+    /** How the create form is surfaced. Defaults to "modal". */
+    createSurface?: "modal" | "inline";
+    /** How the detail view is surfaced. Defaults to "drawer". */
+    detailSurface?: "drawer" | "inline";
+    /** Extra classes on the root container. */
+    className?: string;
+}
+/**
+ * TasksPageCore — a complete, provider-less, BYO-Apollo Tasks experience in a
+ * single mount. Composes the existing `TaskBoardCore`, `CreateTaskCore`, and
+ * `TaskDetailCore` so a host app (e.g. HealthyBowl) doesn't have to wire the
+ * three together itself:
+ *
+ *  - renders the kanban `TaskBoardCore`,
+ *  - a "New task" button opens `CreateTaskCore` (modal or inline),
+ *  - clicking a card opens `TaskDetailCore` (drawer or inline) with inline edit,
+ *  - `CreateTaskCore.onCreated` + `TaskDetailCore.onUpdated` refetch the board.
+ *
+ * BYO-Apollo like the sibling cores: reads the ambient `<ApolloProvider>` and
+ * takes `workspaceId` from a prop or the PlanMagnetProvider context. Semantic
+ * tokens only, farm-free, strict TS.
+ */
+declare function TasksPageCore({ workspaceId: workspaceIdProp, projectId, boardProjectId, columns, readonly, hiddenFields, hideFilters, header, onTaskSaved, createSurface, detailSurface, className, }: TasksPageCoreProps): react.JSX.Element;
+
+interface TasksPageProps extends TasksPageCoreProps {
+    /** Workspace API gateway URL (URL mode). */
+    apiGatewayUrl?: string;
+    /** Platform identity token. */
+    authToken?: string;
+    /** Workspace access token (X-Workspace-Authorization). */
+    workspaceToken?: string;
+    /** Workspace ID. Required. */
+    workspaceId: string;
+    /** Tenant ID. */
+    tenantId?: string;
+    /** Organization ID. */
+    organizationId?: string;
+    /** Optional host allowlist for embedded deployments. */
+    trustedOrigins?: string[];
+    /** Called on UNAUTHENTICATED / FORBIDDEN. */
+    onAuthError?: () => void;
+    /** BYO: provide your own already-authed workspace Apollo client. */
+    workspaceClient?: ApolloClient;
+}
+/**
+ * TasksPage — standalone, embeddable, composed Tasks experience.
+ *
+ * The Phase-3 embed target: a single mount that gives a host app a complete
+ * Tasks page (kanban board + "New task" create flow + click-to-open detail with
+ * inline edit). Thin wrapper that self-provisions (or accepts) an Apollo client
+ * via PlanMagnetProvider, then renders TasksPageCore. Mirrors the
+ * TaskBoard → TaskBoardCore split.
+ *
+ * Two mount modes:
+ *  - URL mode: <TasksPage apiGatewayUrl={..} authToken={..} workspaceId={..} projectId={..} />
+ *  - BYO mode: <TasksPage workspaceClient={hostClient} workspaceId={..} projectId={..} />
+ *
+ * @example BYO client (HealthyBowl shell injects its authed client)
+ * ```tsx
+ * <TasksPage
+ *   workspaceClient={hostClient}
+ *   workspaceId="ws-123"
+ *   projectId="proj-1"
+ *   header="Farm Tasks"
+ *   onTaskSaved={({ workItem, operation }) => console.log(operation, workItem)}
+ * />
+ * ```
+ */
+declare function TasksPage({ apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, organizationId, trustedOrigins, onAuthError, workspaceClient, ...coreProps }: TasksPageProps): react.JSX.Element;
+
+interface PlanMagnetProviderProps {
+    /** Workspace API gateway URL. Required unless a client is injected. */
+    apiGatewayUrl?: string;
+    /** Platform identity token. */
+    authToken?: string;
+    /** Workspace access token (X-Workspace-Authorization). */
+    workspaceToken?: string;
+    /** Workspace ID. Required. */
+    workspaceId: string;
+    /** Tenant ID. */
+    tenantId?: string;
+    /** Organization ID. */
+    organizationId?: string;
+    /** Optional host allowlist for embedded deployments. */
+    trustedOrigins?: string[];
+    /** Called on UNAUTHENTICATED / FORBIDDEN so the host can trigger re-auth. */
+    onAuthError?: () => void;
+    /**
+     * BYO: host shell injects its already-authed workspace Apollo client
+     * (e.g. microfe / HealthyBowl shell). Takes priority over apiGatewayUrl.
+     */
+    workspaceClient?: ApolloClient;
+    /** @deprecated Use workspaceClient instead. */
+    apolloClient?: ApolloClient;
+    children: ReactNode;
+}
+interface PlanMagnetContextValue {
+    apiGatewayUrl?: string;
+    authToken?: string;
+    workspaceId: string;
+    tenantId?: string;
+    organizationId?: string;
+    trustedOrigins?: string[];
+    workspaceClient: ApolloClient;
+}
+/**
+ * PlanMagnetProvider — mirrors the FluidGrids client-injection model.
+ *
+ * Resolution priority for the workspace Apollo client:
+ *   1. `workspaceClient` (host-injected)
+ *   2. `apolloClient` (legacy alias)
+ *   3. `createPlanMagnetClient({ apiGatewayUrl, ... })`
+ * Throws if none of the above is available.
+ *
+ * Unlike the microfe provider, this ALWAYS mounts its own `<ApolloProvider>`
+ * (with the injected-or-built client) so an embedded TaskBoard renders inside
+ * any host page — no reliance on an ambient ApolloProvider.
+ */
+declare function PlanMagnetProvider({ apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, organizationId, trustedOrigins, onAuthError, workspaceClient: externalWorkspaceClient, apolloClient: legacyClient, children, }: PlanMagnetProviderProps): react.JSX.Element;
+declare function usePlanMagnetContext(): PlanMagnetContextValue;
+/**
+ * Safe variant — returns null instead of throwing when used outside a provider.
+ * TaskBoardCore uses this so a `workspaceId` prop can substitute for context.
+ */
+declare function usePlanMagnetContextSafe(): PlanMagnetContextValue | null;
+
+interface PlanMagnetClientConfig {
+    /** Workspace API gateway base URL (e.g. https://graphqlworkspaces.burdenoff.com). */
+    apiGatewayUrl: string;
+    /** Platform identity token → `Authorization: Bearer <authToken>`. */
+    authToken?: string;
+    /** Workspace access token → `X-Workspace-Authorization: Bearer <workspaceToken>`. */
+    workspaceToken?: string;
+    /** Workspace ID → `x-workspace-id`. Required for task queries. */
+    workspaceId: string;
+    /** Tenant ID → `x-tenant-id` (optional). */
+    tenantId?: string;
+    /**
+     * Optional callback invoked when the gateway returns UNAUTHENTICATED / FORBIDDEN
+     * (or a network-level 401/403). Host shells use this to trigger re-auth / logout.
+     */
+    onAuthError?: () => void;
+}
+/**
+ * Create a new Apollo client for the PlanMagnet SDK.
+ *
+ * HTTP-only (no subscriptions) — tasks are read/write over queries + mutations.
+ * Injects the dual-token workspace headers on every request.
+ */
+declare function createPlanMagnetClient(config: PlanMagnetClientConfig): ApolloClient;
+/**
+ * Set the module-level client (SDK-managed mode or wrapper injection).
+ */
+declare function setPlanMagnetClient(client: ApolloClient): void;
+/**
+ * Get the module-level client.
+ * @throws if the client is not initialized.
+ */
+declare function getPlanMagnetClient(): ApolloClient;
+/**
+ * Get the client if available, or null if not initialized.
+ */
+declare function getPlanMagnetClientSafe(): ApolloClient | null;
+/**
+ * Whether the module-level client is ready.
+ */
+declare function isPlanMagnetClientReady(): boolean;
+/**
+ * Poll until the module-level client is initialized (or timeout).
+ */
+declare function waitForPlanMagnetClient(timeoutMs?: number, intervalMs?: number): Promise<ApolloClient | null>;
+/**
+ * Reset the client reference (cleanup on unmount).
+ */
+declare function resetPlanMagnetClient(): void;
+
+/**
+ * PlanMagnet task GraphQL operation documents.
+ *
+ * Hand-written `gql` documents bundled with the SDK. They target the composed
+ * gateway supergraph, whose root fields AND input types are Planmagnet-prefixed
+ * (see wspace-planmagnet-svc/.hive-schema.graphql — the source of truth). A GraphQL
+ * operation's variable *type definitions* are part of the query document and are
+ * validated by the gateway, so the input type names MUST match the schema exactly
+ * (`PlanmagnetCreateWorkItemInput`, `PlanmagnetWorkItemFilter`,
+ * `PlanmagnetPaginationInput`, …). Un-prefixed names pass Apollo MockedProvider
+ * but FAIL live gateway validation ("Unknown type …").
+ *
+ * Phase 3: replace with codegen output after `bun run schema:pull && bun run codegen`.
+ */
+declare const WORK_ITEM_SUMMARY_FIELDS: graphql.DocumentNode;
+declare const WORK_ITEM_FIELDS: graphql.DocumentNode;
+declare const PROJECT_SUMMARY_FIELDS: graphql.DocumentNode;
+declare const LIST_WORK_ITEMS: graphql.DocumentNode;
+declare const GET_WORK_ITEM: graphql.DocumentNode;
+declare const GET_PROJECTS: graphql.DocumentNode;
+declare const CREATE_WORK_ITEM: graphql.DocumentNode;
+declare const UPDATE_WORK_ITEM: graphql.DocumentNode;
+declare const MOVE_WORK_ITEM: graphql.DocumentNode;
+
+/**
+ * Configuration module for the PlanMagnet SDK.
+ */
+/** Result passed to the onTaskSaved callback after a successful create/update. */
+interface TaskSavedResult {
+    /** Work-item row ID. */
+    id: string;
+    /** Human-readable work-item key (e.g. "PM-123"). */
+    key: string;
+    /** Work-item title. */
+    title: string;
+    /** Project the work item belongs to. */
+    projectId: string;
+    /** What kind of save operation occurred. */
+    operation: "created" | "updated";
+}
+interface PlanMagnetConfig {
+    /** GraphQL endpoint URL (workspace gateway). */
+    apiGatewayUrl: string;
+    /** Auth token for API calls. */
+    authToken?: string;
+    /** Current workspace ID. */
+    workspaceId: string;
+    /** Current tenant ID. */
+    tenantId?: string;
+    /** Organization ID. */
+    organizationId?: string;
+    /** Optional allowlist for host origins embedding the SDK. */
+    trustedOrigins?: string[];
+    /** Product ID for host-app isolation (e.g. 'healthybowl', 'workspaces'). */
+    productId?: string;
+    /** Product name for display purposes. */
+    productName?: string;
+    /**
+     * Callback invoked after a work item is successfully created/updated.
+     * Host apps (e.g. HealthyBowl) can use this to sync metadata to their own
+     * backends. Errors thrown here are caught and logged — they never block the save.
+     */
+    onTaskSaved?: (result: TaskSavedResult) => void | Promise<void>;
+}
+/**
+ * Live-access proxy to the current configuration.
+ */
+declare const config: PlanMagnetConfig;
+/**
+ * Get the full configuration object (a copy).
+ */
+declare function getPlanMagnetConfig(): PlanMagnetConfig;
+/**
+ * Merge in runtime configuration.
+ */
+declare function setPlanMagnetConfig(newConfig: Partial<PlanMagnetConfig>): void;
+/**
+ * Reset configuration to defaults.
+ */
+declare function resetPlanMagnetConfig(): void;
+/**
+ * Enforce an optional host-origin allowlist for embedded deployments.
+ * @throws if the current window origin is not in the allowlist.
+ */
+declare function validateTrustedOrigin(trustedOrigins?: string[]): void;
+/**
+ * Resolve the GraphQL endpoint URL.
+ */
+declare function getGraphQLEndpoint(baseUrl?: string): string;
+
+declare const badgeVariants: (props?: ({
+    variant?: "default" | "muted" | "secondary" | "accent" | "destructive" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface BadgeProps extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {
+}
+/**
+ * Badge — a small owned pill primitive used for task status/priority/type.
+ * Semantic-token only.
+ */
+declare function Badge({ className, variant, ...props }: BadgeProps): react.JSX.Element;
+
+interface ModalProps {
+    open: boolean;
+    onClose: () => void;
+    children: ReactNode;
+    ariaLabel?: string;
+    className?: string;
+}
+/** Centered modal card overlay (owned, semantic-token only). */
+declare function Modal(props: ModalProps): react.JSX.Element;
+interface DrawerProps {
+    open: boolean;
+    onClose: () => void;
+    children: ReactNode;
+    ariaLabel?: string;
+    className?: string;
+}
+/** Right-anchored slide-over drawer overlay (owned, semantic-token only). */
+declare function Drawer(props: DrawerProps): react.JSX.Element;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+export { Badge, type BadgeProps, type BoardColumn, CREATE_WORK_ITEM, CreateTask, CreateTaskCore, type CreateTaskCoreProps, type CreateTaskField, type CreateTaskInput, type CreateTaskProps, DEFAULT_BOARD_COLUMNS, Drawer, type DrawerProps, GET_PROJECTS, GET_WORK_ITEM, LIST_WORK_ITEMS, type ListTasksInput, MOVE_WORK_ITEM, Modal, type ModalProps, PROJECT_SUMMARY_FIELDS, type PlanMagnetClientConfig, type PlanMagnetConfig, PlanMagnetProvider, type PlanMagnetProviderProps, type Project, type ProjectList, TASK_PRIORITIES, TASK_STATUSES, TASK_TYPES, type Task, TaskBoard, TaskBoardCore, type TaskBoardCoreProps, type TaskBoardProps, TaskDetail, TaskDetailCore, type TaskDetailCoreProps, type TaskDetailField, type TaskDetailProps, TaskList, type TaskListColumn, TaskListCore, type TaskListCoreProps, type TaskListProps, type TaskListSort, type TaskPageInfo, type TaskPaginationInput, type TaskPriority, type TaskSavedResult, type TaskStatus, type TaskType, TasksPage, TasksPageCore, type TasksPageCoreProps, type TasksPageField, type TasksPageProps, type TasksPageSaved, UPDATE_WORK_ITEM, type UpdateTaskInput, WORK_ITEM_FIELDS, WORK_ITEM_SUMMARY_FIELDS, type WorkItemDetail, type WorkItemLinkRelation, type WorkItemList, badgeVariants, cn, config, createPlanMagnetClient, enumLabel, getGraphQLEndpoint, getPlanMagnetClient, getPlanMagnetClientSafe, getPlanMagnetConfig, isPlanMagnetClientReady, resetPlanMagnetClient, resetPlanMagnetConfig, setPlanMagnetClient, setPlanMagnetConfig, usePlanMagnetContext, usePlanMagnetContextSafe, validateTrustedOrigin, waitForPlanMagnetClient };