@korso/shepherd-ui 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,149 @@
+import { ListWorkspacesResponseT, CreateWorkspaceRequestT, CreateWorkspaceResponseT, MintTokenRequestT, MintTokenResponseT, ListTokensResponseT, CreateInviteRequestT, InviteResponseT, RedeemInviteResponseT, ListMembersResponseT, WorkspaceLandscapeResponseT, WorkspaceAnnounceRequestT, WorkspaceAnnounceResponseT, WorkspaceSummaryT } from '@shepherd/shared';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Caller-supplied configuration. No auth types here on purpose: `getAuthHeader`
+ * returns whatever header value the host's auth scheme produces (or none).
+ */
+interface ShepherdClientConfig {
+    /** Hub base URL, e.g. "https://hub.example.com" or "" for same-origin. */
+    baseUrl: 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 into the request headers, or
+     *   - undefined  → no auth header added (same-origin BFF supplies the cookie).
+     * May be 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>;
+}
+/**
+ * Thrown on any non-2xx Hub response. Carries the HTTP status/statusText and the
+ * parsed error body (if the response carried JSON) so callers can branch on
+ * `status` (e.g. 401 → re-auth, 403 → not a member) without re-reading the body.
+ */
+declare class ShepherdHttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: unknown;
+    constructor(status: number, statusText: string, body: unknown);
+}
+/**
+ * The typed Hub management surface. Workspace-scoped methods take an explicit
+ * `workspaceId` and use the `/workspaces/:id/...` form, which works in both
+ * deployments: a bearer credential resolves its own workspace and ignores the
+ * `:id`, while a browser session validates membership of `:id`.
+ */
+interface ShepherdClient {
+    readonly baseUrl: string;
+    listWorkspaces(): Promise<ListWorkspacesResponseT>;
+    createWorkspace(body: CreateWorkspaceRequestT): Promise<CreateWorkspaceResponseT>;
+    mintToken(workspaceId: string, body: MintTokenRequestT): Promise<MintTokenResponseT>;
+    listTokens(workspaceId: string): Promise<ListTokensResponseT>;
+    revokeToken(workspaceId: string, tokenId: string): Promise<void>;
+    createInvite(workspaceId: string, body: CreateInviteRequestT): Promise<InviteResponseT>;
+    revokeInvite(workspaceId: string, code: string): Promise<void>;
+    redeemInvite(code: string): Promise<RedeemInviteResponseT>;
+    listMembers(workspaceId: string): Promise<ListMembersResponseT>;
+    removeMember(workspaceId: string, accountId: string): Promise<void>;
+    leave(workspaceId: string): Promise<void>;
+    landscape(workspaceId: string): Promise<WorkspaceLandscapeResponseT>;
+    announce(workspaceId: string, body: WorkspaceAnnounceRequestT): Promise<WorkspaceAnnounceResponseT>;
+}
+/**
+ * Create a Shepherd Hub client. The returned object holds no per-instance mutable
+ * state beyond the captured config, so a stable `config` reference yields a stable
+ * client; the provider memoises on the config identity.
+ */
+declare function createShepherdClient(config: ShepherdClientConfig): ShepherdClient;
+
+interface ShepherdProviderProps {
+    /** A pre-built client. Mutually exclusive with `config`. */
+    client?: ShepherdClient;
+    /** Config to build a client from, when one is not supplied directly. */
+    config?: ShepherdClientConfig;
+    children: ReactNode;
+}
+declare function ShepherdProvider({ client, config, children }: ShepherdProviderProps): react.JSX.Element;
+/** Access the ShepherdClient from context. Throws if used outside a provider. */
+declare function useShepherdClient(): ShepherdClient;
+
+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 function ShepherdRoot({ hubUrl }: ShepherdRootProps): react.JSX.Element;
+
+interface TasksProps {
+    /** The workspace whose wallboard to render. Selected by the shell. */
+    workspaceId: string;
+}
+declare function Tasks({ workspaceId }: TasksProps): react.JSX.Element;
+
+interface ChatProps {
+    /** The workspace whose chat to render. Selected by the shell. */
+    workspaceId: string;
+}
+declare function Chat({ workspaceId }: ChatProps): react.JSX.Element;
+
+interface ConfigProps {
+    workspaces: WorkspaceSummaryT[];
+    selected: WorkspaceSummaryT | null;
+    /** The DIRECT Hub URL embedded in the agent install command (decision #2). */
+    hubUrl?: string;
+    /** Refetch the workspace list after a create/join. */
+    onChanged: () => void;
+    /** Switch the active workspace. */
+    onSelect?: (workspaceId: string) => void;
+}
+declare function Config({ workspaces, selected, hubUrl, onChanged, onSelect }: ConfigProps): react.JSX.Element;
+
+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 function ConnectAgent({ workspaceId, hubUrl }: ConnectAgentProps): react.JSX.Element;
+
+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;
+}
+declare function Workspaces({ workspaces, selected, onChanged, onSelect }: WorkspacesProps): react.JSX.Element;
+
+interface MembersProps {
+    workspaceId: string;
+    /** Bumped by the parent to force a refetch (e.g. after an invite is redeemed). */
+    refreshKey?: number;
+}
+declare function Members({ workspaceId, refreshKey }: MembersProps): react.JSX.Element;
+
+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 function EmptyState({ title, children, onGetStarted, ctaLabel, }: EmptyStateProps): react.JSX.Element;
+
+export { Chat, type ChatProps, Config, type ConfigProps, ConnectAgent, type ConnectAgentProps, EmptyState, type EmptyStateProps, Members, type MembersProps, type ShepherdClient, type ShepherdClientConfig, ShepherdHttpError, ShepherdProvider, type ShepherdProviderProps, ShepherdRoot, type ShepherdRootProps, Tasks, type TasksProps, Workspaces, type WorkspacesProps, createShepherdClient, useShepherdClient };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Public `.` entry for `@korso/shepherd-ui` — the auth-agnostic surface hosted
+ * consumers import. It deliberately does NOT export {@link SelfHostApp} (the
+ * token-gated self-host root lives behind the `./selfhost` export) and does NOT
+ * import `styles.css` — hosted consumers opt into styling via
+ * `@korso/shepherd-ui/styles.css`. This keeps the token gate out of `.` so the
+ * core stays auth-neutral.
+ */
+export { createShepherdClient, ShepherdClientError, describeError, } from "./client.js";
+export type { ShepherdClient, ShepherdClientConfig } from "./client.js";
+export { ShepherdClientProvider, useShepherdClient, } from "./context.js";
+export { ShepherdRoot } from "./ShepherdRoot.js";
+export type { ShepherdRootProps } from "./ShepherdRoot.js";
+export { Dashboard } from "./components/Dashboard.js";
+export type { DashboardProps } from "./components/Dashboard.js";
+export { Workspaces, Members, ConnectAgent, EmptyState, } from "./config/index.js";
+export type { WorkspacesProps, MembersProps, ConnectAgentProps, EmptyStateProps, } from "./config/index.js";
+export type { WorkspaceLandscapeResponseT, WorkspaceSummaryT, TokenSummaryT, MemberSummaryT, InviteResponseT, } from "@shepherd/shared";

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * Public `.` entry for `@korso/shepherd-ui` — the auth-agnostic surface hosted
+ * consumers import. It deliberately does NOT export {@link SelfHostApp} (the
+ * token-gated self-host root lives behind the `./selfhost` export) and does NOT
+ * import `styles.css` — hosted consumers opt into styling via
+ * `@korso/shepherd-ui/styles.css`. This keeps the token gate out of `.` so the
+ * core stays auth-neutral.
+ */
+export { createShepherdClient, ShepherdClientError, describeError, } from "./client.js";
+export { ShepherdClientProvider, useShepherdClient, } from "./context.js";
+export { ShepherdRoot } from "./ShepherdRoot.js";
+export { Dashboard } from "./components/Dashboard.js";
+// Config screens — re-exported so consumers can compose the management surface
+// directly without the full ShepherdRoot shell.
+export { Workspaces, Members, ConnectAgent, EmptyState, } from "./config/index.js";