@korso/shepherd-ui 0.1.1 → 0.2.0

package/dist/lib/index.d.ts

@@ -1,19 +1,75 @@
+import { JSX as JSX_2 } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { z } from 'zod';
 
+export declare function ConnectAgent({ workspaceId, hubUrl }: ConnectAgentProps): JSX_2.Element;
+
+export declare interface ConnectAgentProps {
+    workspaceId: string;
+    /**
+     * The DIRECT Hub URL the agent connects to (public Cloud Run URL when hosted).
+     * Defaults to the dashboard client's baseUrl, which is correct for self-host
+     * where the agent and the dashboard share the Hub origin.
+     */
+    hubUrl?: string;
+}
+
+declare const CreateInviteRequest: z.ZodObject<{
+    expiresInDays: z.ZodOptional<z.ZodNumber>;
+    maxUses: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    expiresInDays?: number | undefined;
+    maxUses?: number | undefined;
+}, {
+    expiresInDays?: number | undefined;
+    maxUses?: number | undefined;
+}>;
+
+declare type CreateInviteRequestT = z.infer<typeof CreateInviteRequest>;
+
 /**
- * Builds a browser fetch client for the Shepherd hub with exactly two methods.
- * Each call wires up an AbortController timeout (cleared in `finally`), merges
- * the injected auth headers over a JSON content-type base, and Zod-parses ONLY
- * the response at the boundary — the request body is forwarded verbatim because
- * the caller owns its input shape.
+ * Builds a browser fetch client for the Shepherd hub. Each call wires up an
+ * AbortController timeout (cleared in `finally`), merges the injected auth
+ * headers over a JSON content-type base, and Zod-parses ONLY the response at
+ * the boundary — the request body is forwarded verbatim because the caller owns
+ * its input shape. void-returning methods (revoke/remove/leave) await the
+ * request and parse nothing.
  *
  * @param config - Base URL, optional injected auth, 401 hook, and timeout.
  * @returns A {@link ShepherdClient}.
  */
 export declare function createShepherdClient(config: ShepherdClientConfig): ShepherdClient;
 
+declare const CreateWorkspaceRequest: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+
+declare type CreateWorkspaceRequestT = z.infer<typeof CreateWorkspaceRequest>;
+
+declare const CreateWorkspaceResponse: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    name: z.ZodString;
+    role: z.ZodEnum<["admin", "member"]>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    slug: string;
+    role: "admin" | "member";
+}, {
+    id: string;
+    name: string;
+    slug: string;
+    role: "admin" | "member";
+}>;
+
+declare type CreateWorkspaceResponseT = z.infer<typeof CreateWorkspaceResponse>;
+
 /**
  * The Shepherd wallboard shell. Composes {@link useLandscapePolling} (which reads
  * the client from context, keeping this auth-agnostic) with the six leaf
@@ -36,16 +92,309 @@ export declare function createShepherdClient(config: ShepherdClientConfig): Shep
  *
  * @returns The dashboard element.
  */
-export declare function Dashboard(): ReactElement;
+export declare function Dashboard({ workspaceId }?: DashboardProps): ReactElement;
 
-/** Props for {@link Dashboard}. Currently empty — the client comes from context. */
-export declare type DashboardProps = Record<string, never>;
+/** Props for {@link Dashboard}. The client comes from context. */
+export declare interface DashboardProps {
+    /**
+     * Workspace to scope the board to. When given, the polling hook hits the
+     * workspace-scoped `landscape(id)` route and the composer posts via
+     * `announceTo(id, …)`; when omitted, both fall back to the self-host singular
+     * aliases, so a no-id render is unchanged.
+     */
+    workspaceId?: string;
+}
 
 /**
- * The wallboard's two read/write operations against the Shepherd hub. Responses
- * are Zod-parsed at the boundary so callers receive contract-typed values.
+ * Maps any thrown value into a short, human-friendly message for the view layer.
+ * A {@link ShepherdClientError} (and any other `Error`) surfaces its own
+ * `message` — which already carries the hub's detail for non-2xx responses and a
+ * transport description otherwise — while a non-Error value degrades to a
+ * generic line rather than stringifying something unprintable.
+ *
+ * @param err - The caught value (typically from a client method rejection).
+ * @returns A display-ready message string.
+ */
+export declare function describeError(err: unknown): string;
+
+export declare function EmptyState({ title, children, onGetStarted, ctaLabel, }: EmptyStateProps): JSX_2.Element;
+
+export declare interface EmptyStateProps {
+    /** Heading text. Defaults to a generic "no workspace yet" prompt. */
+    title?: string;
+    /** Supporting copy. */
+    children?: ReactNode;
+    /** Invoked when the user clicks the call-to-action (e.g. switch to Config). */
+    onGetStarted?: () => void;
+    /** CTA label. */
+    ctaLabel?: string;
+}
+
+declare const InviteResponse: z.ZodObject<{
+    code: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodString>;
+    maxUses: z.ZodNumber;
+    useCount: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    expiresAt: string | null;
+    maxUses: number;
+    useCount: number;
+}, {
+    code: string;
+    expiresAt: string | null;
+    maxUses: number;
+    useCount: number;
+}>;
+
+export declare type InviteResponseT = z.infer<typeof InviteResponse>;
+
+declare const ListMembersResponse: z.ZodObject<{
+    members: z.ZodArray<z.ZodObject<{
+        accountId: z.ZodString;
+        displayName: z.ZodNullable<z.ZodString>;
+        githubLogin: z.ZodNullable<z.ZodString>;
+        avatarUrl: z.ZodNullable<z.ZodString>;
+        role: z.ZodEnum<["admin", "member"]>;
+    }, "strip", z.ZodTypeAny, {
+        role: "admin" | "member";
+        accountId: string;
+        displayName: string | null;
+        githubLogin: string | null;
+        avatarUrl: string | null;
+    }, {
+        role: "admin" | "member";
+        accountId: string;
+        displayName: string | null;
+        githubLogin: string | null;
+        avatarUrl: string | null;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    members: {
+        role: "admin" | "member";
+        accountId: string;
+        displayName: string | null;
+        githubLogin: string | null;
+        avatarUrl: string | null;
+    }[];
+}, {
+    members: {
+        role: "admin" | "member";
+        accountId: string;
+        displayName: string | null;
+        githubLogin: string | null;
+        avatarUrl: string | null;
+    }[];
+}>;
+
+declare type ListMembersResponseT = z.infer<typeof ListMembersResponse>;
+
+declare const ListTokensResponse: z.ZodObject<{
+    tokens: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        lastUsedAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        revokedAt: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        createdAt: string;
+        name: string | null;
+        lastUsedAt: string | null;
+        revokedAt: string | null;
+    }, {
+        id: string;
+        createdAt: string;
+        name: string | null;
+        lastUsedAt: string | null;
+        revokedAt: string | null;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    tokens: {
+        id: string;
+        createdAt: string;
+        name: string | null;
+        lastUsedAt: string | null;
+        revokedAt: string | null;
+    }[];
+}, {
+    tokens: {
+        id: string;
+        createdAt: string;
+        name: string | null;
+        lastUsedAt: string | null;
+        revokedAt: string | null;
+    }[];
+}>;
+
+declare type ListTokensResponseT = z.infer<typeof ListTokensResponse>;
+
+declare const ListWorkspacesResponse: z.ZodObject<{
+    workspaces: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<["admin", "member"]>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        slug: string;
+        role: "admin" | "member";
+    }, {
+        id: string;
+        name: string;
+        slug: string;
+        role: "admin" | "member";
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    workspaces: {
+        id: string;
+        name: string;
+        slug: string;
+        role: "admin" | "member";
+    }[];
+}, {
+    workspaces: {
+        id: string;
+        name: string;
+        slug: string;
+        role: "admin" | "member";
+    }[];
+}>;
+
+declare type ListWorkspacesResponseT = z.infer<typeof ListWorkspacesResponse>;
+
+export declare function Members({ workspaceId, refreshKey, canRemove, onLeft }: MembersProps): JSX_2.Element;
+
+export declare interface MembersProps {
+    workspaceId: string;
+    /** Bumped by the parent to force a refetch (e.g. after an invite is redeemed). */
+    refreshKey?: number;
+    /** When true, render the per-member remove control (the caller gates on admin). */
+    canRemove?: boolean;
+    /** Called after a successful self-service leave, so the shell can refresh. */
+    onLeft?: () => void;
+}
+
+declare const MemberSummary: z.ZodObject<{
+    accountId: z.ZodString;
+    displayName: z.ZodNullable<z.ZodString>;
+    githubLogin: z.ZodNullable<z.ZodString>;
+    avatarUrl: z.ZodNullable<z.ZodString>;
+    role: z.ZodEnum<["admin", "member"]>;
+}, "strip", z.ZodTypeAny, {
+    role: "admin" | "member";
+    accountId: string;
+    displayName: string | null;
+    githubLogin: string | null;
+    avatarUrl: string | null;
+}, {
+    role: "admin" | "member";
+    accountId: string;
+    displayName: string | null;
+    githubLogin: string | null;
+    avatarUrl: string | null;
+}>;
+
+export declare type MemberSummaryT = z.infer<typeof MemberSummary>;
+
+declare const MintTokenRequest: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name?: string | undefined;
+}, {
+    name?: string | undefined;
+}>;
+
+declare type MintTokenRequestT = z.infer<typeof MintTokenRequest>;
+
+declare const MintTokenResponse: z.ZodObject<{
+    token: z.ZodString;
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    token: string;
+}, {
+    id: string;
+    token: string;
+}>;
+
+declare type MintTokenResponseT = z.infer<typeof MintTokenResponse>;
+
+declare const RedeemInviteResponse: z.ZodObject<{
+    workspace: z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<["admin", "member"]>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        slug: string;
+        role: "admin" | "member";
+    }, {
+        id: string;
+        name: string;
+        slug: string;
+        role: "admin" | "member";
+    }>;
+}, "strip", z.ZodTypeAny, {
+    workspace: {
+        id: string;
+        name: string;
+        slug: string;
+        role: "admin" | "member";
+    };
+}, {
+    workspace: {
+        id: string;
+        name: string;
+        slug: string;
+        role: "admin" | "member";
+    };
+}>;
+
+declare type RedeemInviteResponseT = z.infer<typeof RedeemInviteResponse>;
+
+/**
+ * The typed Shepherd hub surface. The plural, workspace-scoped methods use the
+ * `/workspaces/:id/...` form (which works in both deployments: a bearer token
+ * resolves its own workspace and ignores `:id`, while a browser session
+ * validates membership of `:id`). The singular `getLandscape()`/`announce()`
+ * pair are the self-host aliases against the implicit single-workspace routes.
+ * Every response with a dedicated schema is Zod-parsed at the boundary so a
+ * contract drift throws `Invalid response schema` rather than flowing a
+ * malformed object into the view layer.
  */
 export declare interface ShepherdClient {
+    /** The normalised (trailing-slash-stripped) hub base URL the client targets. */
+    readonly baseUrl: string;
+    /** GET the caller's workspaces, each tagged with the caller's role. */
+    listWorkspaces(): Promise<ListWorkspacesResponseT>;
+    /** POST a new workspace; the caller becomes its admin. */
+    createWorkspace(body: CreateWorkspaceRequestT): Promise<CreateWorkspaceResponseT>;
+    /** POST a new agent token; the raw `shp_` value is returned exactly once. */
+    mintToken(workspaceId: string, body: MintTokenRequestT): Promise<MintTokenResponseT>;
+    /** GET the workspace's token metadata (never the raw token). */
+    listTokens(workspaceId: string): Promise<ListTokensResponseT>;
+    /** DELETE (revoke) a token by id. */
+    revokeToken(workspaceId: string, tokenId: string): Promise<void>;
+    /** POST a new invite code for the workspace (admin only). */
+    createInvite(workspaceId: string, body: CreateInviteRequestT): Promise<InviteResponseT>;
+    /** POST to revoke an invite code (admin only). */
+    revokeInvite(workspaceId: string, code: string): Promise<void>;
+    /** POST to redeem an invite code, joining its workspace as a member. */
+    redeemInvite(code: string): Promise<RedeemInviteResponseT>;
+    /** GET the workspace's member roster. */
+    listMembers(workspaceId: string): Promise<ListMembersResponseT>;
+    /** DELETE (remove) a member by account id (admin only). */
+    removeMember(workspaceId: string, accountId: string): Promise<void>;
+    /** POST to leave the workspace. */
+    leave(workspaceId: string): Promise<void>;
+    /** GET a specific workspace's landscape (agents, tasks, announcements). */
+    landscape(workspaceId: string): Promise<WorkspaceLandscapeResponseT>;
+    /** POST an operator announcement to a specific workspace. */
+    announceTo(workspaceId: string, body: WorkspaceAnnounceRequestT): Promise<WorkspaceAnnounceResponseT>;
     /** GET the unfiltered whole-workspace view (agents, tasks, announcements). */
     getLandscape(): Promise<WorkspaceLandscapeResponseT>;
     /** POST an operator announcement (broadcast or @targeted) to the workspace. */
@@ -54,15 +403,22 @@ export declare interface ShepherdClient {
 
 /**
  * Construction options for {@link createShepherdClient}. Auth is supplied
- * externally via `getAuthHeaders` so the core client stays auth-agnostic — it
- * never reads tokens, localStorage, or a BFF; it only merges whatever headers
- * the host injects and notifies the host on a 401 via `onUnauthorized`.
+ * externally via `getAuthHeader` so the core client stays auth-agnostic — it
+ * never reads tokens, localStorage, or a BFF; it only merges whatever the host
+ * injects and notifies the host on a 401 via `onUnauthorized`.
  */
 export declare interface ShepherdClientConfig {
-    /** Hub origin; a trailing slash is tolerated and normalised away. */
+    /** Hub origin; a trailing slash is tolerated and normalised away. "" = same-origin. */
     baseUrl: string;
-    /** Returns auth headers to merge over the JSON content-type base, per call. */
-    getAuthHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * Returns the credential for the next request, as either:
+     *   - a string  → sent as the `Authorization` header value (e.g. "Bearer …"),
+     *   - a header map → merged verbatim over the JSON content-type base, or
+     *   - undefined  → no auth header added (same-origin BFF supplies the cookie).
+     * May be sync or async (e.g. refreshing a short-lived token). Omit entirely
+     * for an unauthenticated/same-origin deployment.
+     */
+    getAuthHeader?: () => string | Record<string, string> | undefined | Promise<string | Record<string, string> | undefined>;
     /** Invoked once when the hub responds 401, before the error is thrown. */
     onUnauthorized?: () => void;
     /** Per-request abort timeout in ms; defaults to {@link DEFAULT_TIMEOUT_MS}. */
@@ -105,6 +461,39 @@ declare interface ShepherdClientProviderProps {
     children: ReactNode;
 }
 
+export declare function ShepherdRoot({ hubUrl }: ShepherdRootProps): JSX_2.Element;
+
+export declare interface ShepherdRootProps {
+    /**
+     * The DIRECT Hub URL embedded in the agent install command (planning decision
+     * #2: the headless agent connects straight to the Hub, not the BFF). Defaults
+     * to the client's baseUrl, which is correct for self-host.
+     */
+    hubUrl?: string;
+}
+
+declare const TokenSummary: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    lastUsedAt: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    revokedAt: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    createdAt: string;
+    name: string | null;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+}, {
+    id: string;
+    createdAt: string;
+    name: string | null;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+}>;
+
+export declare type TokenSummaryT = z.infer<typeof TokenSummary>;
+
 /**
  * Reads the {@link ShepherdClient} from context. Throws when called outside a
  * {@link ShepherdClientProvider} so a missing provider surfaces as an immediate,
@@ -303,4 +692,37 @@ declare const WorkspaceLandscapeResponse: z.ZodObject<{
 
 export declare type WorkspaceLandscapeResponseT = z.infer<typeof WorkspaceLandscapeResponse>;
 
+export declare function Workspaces({ workspaces, selected, onChanged, onSelect }: WorkspacesProps): JSX_2.Element;
+
+export declare interface WorkspacesProps {
+    /** All workspaces the account belongs to (for the switcher / context). */
+    workspaces: WorkspaceSummaryT[];
+    /** The currently-selected workspace, or null when the account has none. */
+    selected: WorkspaceSummaryT | null;
+    /** Called after a mutation that changes membership (create / join / leave). */
+    onChanged: () => void;
+    /** Switch the active workspace (optional simple switcher). */
+    onSelect?: (workspaceId: string) => void;
+}
+
+/** One workspace as seen by an account, with that account's role in it. */
+declare const WorkspaceSummary: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    name: z.ZodString;
+    role: z.ZodEnum<["admin", "member"]>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    slug: string;
+    role: "admin" | "member";
+}, {
+    id: string;
+    name: string;
+    slug: string;
+    role: "admin" | "member";
+}>;
+
+export declare type WorkspaceSummaryT = z.infer<typeof WorkspaceSummary>;
+
 export { }