@stigmer/react 3.40.0 → 3.41.0

package/src/billing/ProviderKeysSection.tsx

@@ -0,0 +1,324 @@
+"use client";
+
+import { useCallback, useId, useState } from "react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import type { ProviderKey } from "@stigmer/protos/ai/stigmer/billing/providerkey/v1/api_pb";
+import { Feature } from "@stigmer/protos/ai/stigmer/platform/v1/entitlement_pb";
+import { Button } from "../button/index.js";
+import { ApiResourceKind, useDeploymentMode, useResourceAvailable } from "../deployment-mode.js";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+import { CloudFeatureNotice } from "../internal/CloudFeatureNotice.js";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
+import { useOrg } from "../organization/OrgProvider.js";
+import { lowestPlanWith } from "./plan-features.js";
+import { planUpgradeFeature, UpgradeNotice } from "./UpgradeNotice.js";
+import { useEntitlements } from "./useEntitlements.js";
+import { usePlans } from "./usePlans.js";
+import { useProviderKeyActions, useProviderKeys, type ProviderKeyProvider } from "./useProviderKeys.js";
+
+/** The providers, in the order the section lists them. */
+const PROVIDERS: ReadonlyArray<{ readonly id: ProviderKeyProvider; readonly name: string; readonly placeholder: string }> = [
+  { id: "anthropic", name: "Anthropic", placeholder: "sk-ant-…" },
+  { id: "openai", name: "OpenAI", placeholder: "sk-…" },
+];
+
+/** Props for {@link ProviderKeysSection}. */
+export interface ProviderKeysSectionProps {
+  /** Where the plans are, in the host's routing. Defaults to the billing settings route. */
+  readonly billingHref?: string;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * Settings section for an organization's own LLM provider keys.
+ *
+ * On a plan that includes bring-your-own provider keys (Business and
+ * above), an admin saves an Anthropic or OpenAI key, and the organization's
+ * agents and workflows then run on it: the provider bills the organization
+ * directly, and those tokens carry no Stigmer commission and do not count
+ * toward the plan's usage share. A saved key is never shown again, only its
+ * last four characters. A managed organization is served by its
+ * integrator's key for a provider it holds none of, shown read-only.
+ *
+ * A key the plan no longer allows is kept and listed as not in use, and
+ * can be removed; the organization's calls run on Stigmer's keys again,
+ * billed as usage. Every member sees the list; admins
+ * (`can_manage_billing`) save, replace and remove.
+ *
+ * Cloud-only: in local mode the runner already uses the developer's own
+ * keys directly.
+ *
+ * @example
+ * ```tsx
+ * <ProviderKeysSection />
+ * ```
+ */
+export function ProviderKeysSection({ billingHref, className }: ProviderKeysSectionProps) {
+  const headingId = useId();
+  const { activeOrg } = useOrg();
+  const mode = useDeploymentMode();
+  const available = useResourceAvailable(ApiResourceKind.subscription);
+  const orgId = activeOrg?.metadata?.id ?? "";
+
+  return (
+    <section aria-labelledby={headingId} className={className}>
+      <h2 id={headingId} className="stg:text-foreground stg:mb-1 stg:text-sm stg:font-semibold">
+        Provider keys
+      </h2>
+      <p className="stg:text-muted-foreground stg:mb-4 stg:text-xs">
+        Run your agents on your organization&apos;s own Anthropic and OpenAI keys. The provider bills you directly;
+        those tokens carry no Stigmer commission and do not count toward your plan&apos;s usage share.
+      </p>
+      {mode === "local" || !available ? (
+        <CloudFeatureNotice>
+          Your own provider keys are a Stigmer Cloud plan feature. Local mode already calls the providers with your
+          own keys directly.
+        </CloudFeatureNotice>
+      ) : !orgId ? (
+        <p className="stg:text-muted-foreground stg:py-4 stg:text-center stg:text-xs">
+          Select an organization to manage its provider keys.
+        </p>
+      ) : (
+        <ProviderKeysContent orgId={orgId} billingHref={billingHref} />
+      )}
+    </section>
+  );
+}
+
+function ProviderKeysContent({ orgId, billingHref }: { readonly orgId: string; readonly billingHref?: string }) {
+  const listed = useProviderKeys(orgId);
+  const entitlements = useEntitlements(orgId);
+  const plans = usePlans();
+  const manage = useCheckPermission({ kind: "organization", id: orgId }, "can_manage_billing");
+  const canManage = !manage.isLoading && manage.allowed;
+  const actions = useProviderKeyActions();
+  const [editing, setEditing] = useState<ProviderKeyProvider | null>(null);
+
+  const allowed = entitlements.allows(Feature.byo_provider_keys);
+  const unlockingPlanName = lowestPlanWith(plans.plans ?? [], Feature.byo_provider_keys)?.metadata?.name;
+  const keys = listed.keys ?? [];
+  const refused = planUpgradeFeature(actions.error);
+
+  const refresh = useCallback(() => {
+    listed.refetch();
+    entitlements.refetch();
+  }, [listed, entitlements]);
+
+  if (listed.error) {
+    return <p className="stg:text-destructive stg:text-xs">{getUserMessage(listed.error)}</p>;
+  }
+  if (listed.keys === null || allowed === null) {
+    return <p className="stg:text-muted-foreground stg:text-xs">Loading provider keys…</p>;
+  }
+
+  return (
+    <div className="stg:space-y-3">
+      {!allowed && (
+        <UpgradeNotice feature={Feature.byo_provider_keys} unlockingPlanName={unlockingPlanName} billingHref={billingHref} />
+      )}
+      {!allowed && keys.length > 0 && (
+        <p className="stg:text-muted-foreground stg:text-xs">
+          Your saved keys are kept but not used on this plan: your agents run on Stigmer&apos;s keys, billed as usage.
+          You can remove them at any time.
+        </p>
+      )}
+      <ul
+        aria-label="Provider keys"
+        className={cn(UNSTYLED_LIST, "stg:divide-y stg:divide-border stg:rounded-md stg:border stg:border-border")}
+      >
+        {PROVIDERS.map((provider) => (
+          <ProviderRow
+            key={provider.id}
+            orgId={orgId}
+            provider={provider}
+            stored={keys.find((key) => key.provider === provider.id)}
+            canSave={canManage && allowed}
+            canRemove={canManage}
+            editing={editing === provider.id}
+            onEdit={() => {
+              actions.clearError();
+              setEditing(provider.id);
+            }}
+            onDone={() => {
+              setEditing(null);
+              refresh();
+            }}
+            onCancel={() => setEditing(null)}
+            actions={actions}
+          />
+        ))}
+      </ul>
+      {refused !== null ? (
+        <UpgradeNotice feature={refused} error={actions.error} billingHref={billingHref} />
+      ) : actions.error ? (
+        <p role="alert" className="stg:text-destructive stg:text-xs">
+          {getUserMessage(actions.error)}
+        </p>
+      ) : null}
+      <p className="stg:text-muted-foreground stg:text-[0.65rem]">
+        A failure on your own key, such as a rejected key or an exhausted provider balance, is reported as your key&apos;s;
+        calls are never retried on Stigmer&apos;s keys.
+      </p>
+    </div>
+  );
+}
+
+function ProviderRow({
+  orgId,
+  provider,
+  stored,
+  canSave,
+  canRemove,
+  editing,
+  onEdit,
+  onDone,
+  onCancel,
+  actions,
+}: {
+  readonly orgId: string;
+  readonly provider: (typeof PROVIDERS)[number];
+  readonly stored: ProviderKey | undefined;
+  readonly canSave: boolean;
+  readonly canRemove: boolean;
+  readonly editing: boolean;
+  readonly onEdit: () => void;
+  readonly onDone: () => void;
+  readonly onCancel: () => void;
+  readonly actions: ReturnType<typeof useProviderKeyActions>;
+}) {
+  const inputId = useId();
+  const [value, setValue] = useState("");
+  const [confirming, setConfirming] = useState(false);
+  const inherited = stored !== undefined && stored.inheritedFromOrgId !== "";
+  const own = stored !== undefined && !inherited;
+
+  const save = async () => {
+    try {
+      await actions.setKey(orgId, provider.id, value.trim());
+      setValue("");
+      onDone();
+    } catch {
+      // The hook holds the error; the section renders it.
+    }
+  };
+  const remove = async () => {
+    try {
+      await actions.removeKey(orgId, provider.id);
+      setConfirming(false);
+      onDone();
+    } catch {
+      // The hook holds the error; the section renders it.
+    }
+  };
+
+  return (
+    <li className="stg:space-y-2 stg:px-3 stg:py-2.5">
+      <div className="stg:flex stg:items-start stg:justify-between stg:gap-3">
+        <div className="stg:min-w-0">
+          <p className="stg:text-foreground stg:text-xs stg:font-medium">{provider.name}</p>
+          <p className="stg:text-muted-foreground stg:text-[0.7rem]">{describe(stored)}</p>
+        </div>
+        {!editing && !confirming && (
+          <div className="stg:flex stg:shrink-0 stg:gap-2">
+            {canSave && !inherited && (
+              <Button size="sm" variant="outline" onClick={onEdit} disabled={actions.isSubmitting}>
+                {own ? "Replace" : "Add key"}
+              </Button>
+            )}
+            {canRemove && own && (
+              <Button
+                size="sm"
+                variant="ghost"
+                onClick={() => {
+                  actions.clearError();
+                  setConfirming(true);
+                }}
+                disabled={actions.isSubmitting}
+              >
+                Remove
+              </Button>
+            )}
+          </div>
+        )}
+      </div>
+      {confirming && (
+        <div className="stg:flex stg:flex-wrap stg:items-center stg:justify-between stg:gap-2 stg:rounded-md stg:border stg:border-destructive/30 stg:bg-destructive-subtle stg:px-2.5 stg:py-2">
+          <p className="stg:text-foreground stg:min-w-0 stg:flex-1 stg:text-xs">
+            {stored?.inUse
+              ? `Remove your ${provider.name} key? Your agents' ${provider.name} calls go back to Stigmer's keys, billed as usage.`
+              : `Remove your ${provider.name} key? It is not in use on this plan.`}
+          </p>
+          <div className="stg:flex stg:shrink-0 stg:gap-2">
+            <Button size="sm" variant="destructive" onClick={() => void remove()} disabled={actions.isSubmitting}>
+              {actions.isSubmitting ? "Removing…" : "Remove key"}
+            </Button>
+            <Button size="sm" variant="ghost" onClick={() => setConfirming(false)} disabled={actions.isSubmitting}>
+              Cancel
+            </Button>
+          </div>
+        </div>
+      )}
+      {editing && (
+        <form
+          className="stg:flex stg:flex-wrap stg:items-end stg:gap-2"
+          onSubmit={(event) => {
+            event.preventDefault();
+            void save();
+          }}
+        >
+          <div className="stg:min-w-48 stg:flex-1 stg:space-y-1">
+            <label htmlFor={inputId} className="stg:text-foreground stg:text-xs stg:font-medium">
+              {provider.name} API key
+            </label>
+            <input
+              id={inputId}
+              type="password"
+              autoComplete="off"
+              value={value}
+              onChange={(event) => setValue(event.target.value)}
+              placeholder={provider.placeholder}
+              disabled={actions.isSubmitting}
+              className={cn(
+                "stg:w-full stg:rounded-md stg:border stg:border-input stg:bg-background stg:px-2.5 stg:py-1.5 stg:text-xs stg:text-foreground",
+                "stg:placeholder:text-muted-foreground",
+                "stg:focus-visible:outline-none stg:focus-visible:ring-1 stg:focus-visible:ring-ring",
+                "stg:disabled:pointer-events-none stg:disabled:opacity-50",
+              )}
+            />
+          </div>
+          <Button size="sm" type="submit" disabled={actions.isSubmitting || value.trim() === ""}>
+            {actions.isSubmitting ? "Saving…" : "Save key"}
+          </Button>
+          <Button size="sm" variant="ghost" type="button" onClick={onCancel} disabled={actions.isSubmitting}>
+            Cancel
+          </Button>
+        </form>
+      )}
+    </li>
+  );
+}
+
+/** One line about a provider's key: none, own, or inherited, with its use. */
+function describe(key: ProviderKey | undefined): string {
+  if (key === undefined) {
+    return "Not set: calls run on Stigmer's keys, billed as usage.";
+  }
+  const parts = [`Key ending in ${key.keyHint}`];
+  if (key.inheritedFromOrgId !== "") {
+    parts.push(`provided by ${key.inheritedFromOrgId}`);
+  } else if (key.updatedAt !== undefined) {
+    parts.push(`saved ${formatDay(timestampDate(key.updatedAt))}`);
+  }
+  parts.push(key.lastUsedAt === undefined ? "not used yet" : `last used ${formatDay(timestampDate(key.lastUsedAt))}`);
+  if (!key.inUse) {
+    parts.push("not in use on this plan");
+  }
+  return parts.join(" · ");
+}
+
+function formatDay(date: Date): string {
+  return date.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric", timeZone: "UTC" });
+}

package/src/billing/UpgradeNotice.tsx

@@ -18,6 +18,7 @@ export const DEFAULT_BILLING_HREF = "/settings/billing";
 const FEATURE_BY_WIRE_NAME: Readonly<Record<string, Feature>> = {
   teams: Feature.teams,
   managed_organizations: Feature.managed_organizations,
+  byo_provider_keys: Feature.byo_provider_keys,
 };
 
 /**

package/src/billing/index.ts

@@ -20,6 +20,13 @@ export { useEntitlements } from "./useEntitlements.js";
 export type { UseEntitlementsOptions, UseEntitlementsReturn } from "./useEntitlements.js";
 export { usePeriodEstimate } from "./usePeriodEstimate.js";
 export type { UsePeriodEstimateOptions, UsePeriodEstimateReturn } from "./usePeriodEstimate.js";
+export { useProviderKeys, useProviderKeyActions } from "./useProviderKeys.js";
+export type {
+  ProviderKeyProvider,
+  UseProviderKeysOptions,
+  UseProviderKeysReturn,
+  UseProviderKeyActionsReturn,
+} from "./useProviderKeys.js";
 
 // Behavior hooks
 export { useCreateCheckoutSession } from "./useCreateCheckoutSession.js";
@@ -43,6 +50,8 @@ export type {
 } from "./useSetAutoRechargeConfig.js";
 
 // Styled components
+export { ProviderKeysSection } from "./ProviderKeysSection.js";
+export type { ProviderKeysSectionProps } from "./ProviderKeysSection.js";
 export { BillingSection } from "./BillingSection.js";
 export type { BillingSectionProps } from "./BillingSection.js";
 export { CreditBalanceCard } from "./CreditBalanceCard.js";

package/src/billing/plan-features.ts

@@ -24,10 +24,11 @@ const ZERO = BigInt(0);
 /**
  * Features a plan may list ahead of the gate that serves them, which
  * Stigmer Cloud does not offer yet. The console leaves them out of every
- * comparison. Bring-your-own provider keys leaves this set when the proxy
- * uses an organization's own key.
+ * comparison. Empty while every listed feature is served; bring-your-own
+ * provider keys left it when the proxy began serving an organization's own
+ * key (stigmer/stigmer#1425).
  */
-export const NOT_YET_OFFERED: ReadonlySet<Feature> = new Set([Feature.byo_provider_keys]);
+export const NOT_YET_OFFERED: ReadonlySet<Feature> = new Set<Feature>();
 
 /** One feature a plan offers today, with its words. */
 export interface OfferedFeature {

package/src/billing/useProviderKeys.ts

@@ -0,0 +1,129 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { ProviderKey } from "@stigmer/protos/ai/stigmer/billing/providerkey/v1/api_pb";
+import {
+  DeleteProviderKeyInputSchema,
+  ListProviderKeysInputSchema,
+  SetProviderKeyInputSchema,
+} from "@stigmer/protos/ai/stigmer/billing/providerkey/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** The providers an organization may bring its own key for, by their wire names. */
+export type ProviderKeyProvider = "anthropic" | "openai";
+
+/** Options for {@link useProviderKeys}. */
+export interface UseProviderKeysOptions {
+  /** Skip fetching while `false` (stable no-op). Default `true`. */
+  readonly enabled?: boolean;
+}
+
+/** Return value of {@link useProviderKeys}. */
+export interface UseProviderKeysReturn {
+  /**
+   * The keys that serve the organization, its own and any it inherits from
+   * its integrator, without their secrets; `null` before the first
+   * successful fetch.
+   */
+  readonly keys: readonly ProviderKey[] | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that lists an organization's own LLM provider keys.
+ *
+ * No answer carries a key: each row names the provider, the key's last
+ * four characters, who saved it and when, when it last served a call, and
+ * whether the organization's plan still lets it be used. A managed
+ * organization's list includes its integrator's keys for the providers it
+ * holds none of (`inheritedFromOrgId`). Every member may read it
+ * (`can_view_billing`).
+ *
+ * Cloud-only.
+ *
+ * @example
+ * ```tsx
+ * const { keys } = useProviderKeys(orgId);
+ * ```
+ */
+export function useProviderKeys(orgId: string | null, options?: UseProviderKeysOptions): UseProviderKeysReturn {
+  const stigmer = useStigmer();
+  const enabled = (options?.enabled ?? true) && orgId !== null && orgId !== "";
+  const { data, isLoading, error, refetch } = useFetch(
+    enabled && orgId ? () => stigmer.providerkey.list(create(ListProviderKeysInputSchema, { orgId })) : null,
+    [enabled, orgId, stigmer],
+    null as { readonly keys: readonly ProviderKey[] } | null,
+  );
+  const keys = data?.keys ?? null;
+  return useMemo(() => ({ keys, isLoading, error, refetch }), [keys, isLoading, error, refetch]);
+}
+
+/** Return value of {@link useProviderKeyActions}. */
+export interface UseProviderKeyActionsReturn {
+  /**
+   * Save the organization's key for a provider, replacing any it holds.
+   * The provider is asked about the key once first, and a key it rejects is
+   * refused. Refused with the `PLAN_UPGRADE_REQUIRED` reason when the
+   * organization's plan does not include bring-your-own provider keys.
+   * Resolves with the saved key, without its secret.
+   */
+  readonly setKey: (orgId: string, provider: ProviderKeyProvider, apiKey: string) => Promise<ProviderKey>;
+  /** Remove the organization's key for a provider; allowed on every plan. */
+  readonly removeKey: (orgId: string, provider: ProviderKeyProvider) => Promise<ProviderKey>;
+  /** `true` while a save or a removal is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behaviour hook that saves and removes an organization's own provider
+ * keys. The caller needs `can_manage_billing` on the organization (its
+ * admins). Refetch {@link useProviderKeys} after a change.
+ */
+export function useProviderKeyActions(): UseProviderKeyActionsReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const run = useCallback(async (call: () => Promise<ProviderKey>): Promise<ProviderKey> => {
+    setIsSubmitting(true);
+    setError(null);
+    try {
+      return await call();
+    } catch (e) {
+      const err = toError(e);
+      setError(err);
+      throw err;
+    } finally {
+      setIsSubmitting(false);
+    }
+  }, []);
+
+  const setKey = useCallback(
+    (orgId: string, provider: ProviderKeyProvider, apiKey: string) =>
+      run(() => stigmer.providerkey.set(create(SetProviderKeyInputSchema, { orgId, provider, apiKey }))),
+    [run, stigmer.providerkey],
+  );
+  const removeKey = useCallback(
+    (orgId: string, provider: ProviderKeyProvider) =>
+      run(() => stigmer.providerkey.delete(create(DeleteProviderKeyInputSchema, { orgId, provider }))),
+    [run, stigmer.providerkey],
+  );
+  const clearError = useCallback(() => setError(null), []);
+
+  return useMemo(
+    () => ({ setKey, removeKey, isSubmitting, error, clearError }),
+    [setKey, removeKey, isSubmitting, error, clearError],
+  );
+}

package/src/channel/AgentChannelsPanel.tsx

@@ -119,19 +119,21 @@ export function AgentChannelsPanel({
   // label worth showing.
   const { channelApps } = useChannelAppList(agent.metadata?.org || null);
 
-  // Mirrors the server's create bar (agent can_edit — the permission the
-  // create/apply handlers enforce on the referenced agent) so the connect
-  // affordance never appears to a viewer whose create would be refused.
+  // Mirrors the server's create bar (agent can_manage_audience — the
+  // permission the create/apply handlers enforce on the referenced agent:
+  // a channel puts the agent in front of a wider audience, the owner's
+  // decision, not an editor's) so the connect affordance never appears to
+  // someone whose create would be refused.
   const { allowed: canCreate } = useCheckPermission(
     agentId ? { kind: "agent", id: agentId } : null,
-    "can_edit",
+    "can_manage_audience",
   );
 
-  // Installs go through the shared platform Slack/WhatsApp apps, a
-  // cloud-only facility (editions program, DD-001); CRUD is not. Outside
-  // Cloud the cards render and toggles work, but connect affordances give
-  // way to the notice. Installs through a customer's own ChannelApp in
-  // Enterprise are that edition's work, not assumed here.
+  // Installs need a channel delivery runtime, and only Stigmer Cloud
+  // composes one today; CRUD needs none. Outside Cloud the cards render and
+  // toggles work, but connect affordances give way to the notice. When a
+  // self-hosted edition composes a runtime, this becomes a probe of that
+  // runtime rather than an edition compare.
   const installsAvailable = useDeploymentMode() === "cloud";
 
   const { deleteChannel } = useDeleteAgentChannel();

package/src/channel/connect/ServingAppSection.tsx

@@ -175,7 +175,7 @@ function ServingAppOption({
         checked={checked}
         onChange={onSelect}
         disabled={disabled}
-        className="stg:mt-0.5 stg:accent-current"
+        className="stg:mt-0.5"
       />
       <span className="stg:min-w-0">
         <span className="stg:block stg:text-xs stg:font-medium stg:text-foreground">{label}</span>