@opengeni/sdk 3.1.0 → 3.1.2

package/src/usage-allowances.ts

@@ -0,0 +1,189 @@
+// @opengeni/sdk/usage-allowances — usage allowance reads and administration as
+// free functions over any client's `requestJson`, so a browser console can use
+// them without widening the native browser client. The root `OpenGeniClient`
+// methods of the same names call the same routes.
+//
+// Amounts are integer USD micros (1 USD = 1,000,000). Display `fraction` and
+// `status` in products that must not show money; see docs/usage-allowances.md.
+import type { OpenGeniClient, OpenGeniRequestOptions } from "./client";
+import type {
+  ClearWorkspaceAllowanceRequest,
+  ClearWorkspaceAllowanceResponse,
+  GetMyUsageRequest,
+  GetUsageRequest,
+  GrantWorkspaceCreditsRequest,
+  MemberAllowance,
+  SetMemberAllowanceRequest,
+  SetWorkspaceAllowanceRequest,
+  WorkspaceAllowance,
+  WorkspaceAllowanceState,
+  WorkspaceCreditGrant,
+  WorkspaceUsageResponse,
+} from "@opengeni/contracts/usage-allowances";
+
+export type {
+  AllowanceExhaustedRefusal,
+  ClearWorkspaceAllowanceRequest,
+  ClearWorkspaceAllowanceResponse,
+  GetMyUsageRequest,
+  GetUsageRequest,
+  GrantWorkspaceCreditsRequest,
+  MemberAllowance,
+  MemberAllowanceDefault,
+  MemberAllowanceRule,
+  MemberAllowanceUsage,
+  SetMemberAllowanceRequest,
+  SetWorkspaceAllowanceRequest,
+  UsageAllowancePeriod,
+  UsageAllowanceStatus,
+  UsageAllowanceWindow,
+  WorkspaceAllowance,
+  WorkspaceAllowanceConfig,
+  WorkspaceAllowanceState,
+  WorkspaceAllowanceUsage,
+  WorkspaceCreditGrant,
+  WorkspaceUsageResponse,
+} from "@opengeni/contracts/usage-allowances";
+
+/** The one client capability these functions need. */
+export type UsageAllowanceRequestClient = Pick<OpenGeniClient, "requestJson">;
+
+/** A member target: canonical subject id, or an external identity. */
+export type UsageAllowanceMemberTarget = string | { source: string; externalId: string };
+
+function workspacePath(workspaceId: string): string {
+  return `/v1/workspaces/${encodeURIComponent(workspaceId)}`;
+}
+
+/** Query strings for usage reads: only defined values, stringified. */
+export function usageAllowanceQuery(query: GetUsageRequest): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(query)
+      .filter(([, value]) => value !== undefined)
+      .map(([key, value]) => [key, String(value)]),
+  );
+}
+
+/** Configuration, or null when no ceiling is configured. Budget-read authority. */
+export async function getWorkspaceAllowance(
+  client: UsageAllowanceRequestClient,
+  workspaceId: string,
+): Promise<WorkspaceAllowance | null> {
+  return await client.requestJson("GET", `${workspacePath(workspaceId)}/allowance`);
+}
+
+/** Lifecycle version plus configuration; version survives a clear. Budget-read authority. */
+export async function getWorkspaceAllowanceState(
+  client: UsageAllowanceRequestClient,
+  workspaceId: string,
+): Promise<WorkspaceAllowanceState> {
+  return await client.requestJson("GET", `${workspacePath(workspaceId)}/allowance/state`);
+}
+
+/**
+ * Set the workspace ceiling with exact-version compare-and-set. Requires a
+ * verified organization administrator or a full-access organization key.
+ */
+export async function setWorkspaceAllowance(
+  client: UsageAllowanceRequestClient,
+  workspaceId: string,
+  request: SetWorkspaceAllowanceRequest,
+): Promise<WorkspaceAllowance> {
+  return await client.requestJson("PUT", `${workspacePath(workspaceId)}/allowance`, request);
+}
+
+/** Remove the ceiling (not a refund or counter reset). Returns the next lifecycle version. */
+export async function clearWorkspaceAllowance(
+  client: UsageAllowanceRequestClient,
+  workspaceId: string,
+  request: ClearWorkspaceAllowanceRequest,
+): Promise<ClearWorkspaceAllowanceResponse> {
+  return await client.requestJson("DELETE", `${workspacePath(workspaceId)}/allowance`, request);
+}
+
+/** One-off credits on top of the included amount. Reuse the operationId to retry. */
+export async function grantWorkspaceCredits(
+  client: UsageAllowanceRequestClient,
+  workspaceId: string,
+  request: GrantWorkspaceCreditsRequest,
+): Promise<WorkspaceCreditGrant> {
+  return await client.requestJson(
+    "POST",
+    `${workspacePath(workspaceId)}/allowance/grants`,
+    request,
+  );
+}
+
+/**
+ * Set or restore (`rule: null`) one member's ceiling with exact-version CAS.
+ * Shares may oversubscribe the pool; the workspace ceiling still binds.
+ */
+export async function setMemberAllowance(
+  client: UsageAllowanceRequestClient,
+  workspaceId: string,
+  member: UsageAllowanceMemberTarget,
+  request: SetMemberAllowanceRequest,
+): Promise<MemberAllowance> {
+  const path =
+    typeof member === "string"
+      ? encodeURIComponent(member)
+      : `external/${encodeURIComponent(member.source)}/${encodeURIComponent(member.externalId)}`;
+  return await client.requestJson(
+    "PUT",
+    `${workspacePath(workspaceId)}/members/${path}/allowance`,
+    request,
+  );
+}
+
+/** The paginated roster page. Workspace admin, organization admin, or org-key read. */
+export async function getUsage(
+  client: UsageAllowanceRequestClient,
+  workspaceId: string,
+  query: GetUsageRequest = {},
+  options: OpenGeniRequestOptions = {},
+): Promise<WorkspaceUsageResponse> {
+  return await client.requestJson(
+    "GET",
+    `${workspacePath(workspaceId)}/usage`,
+    undefined,
+    usageAllowanceQuery(query),
+    options,
+  );
+}
+
+/** The caller's own row plus the workspace aggregate. Any authenticated member. */
+export async function getMyUsage(
+  client: UsageAllowanceRequestClient,
+  workspaceId: string,
+  query: GetMyUsageRequest = {},
+  options: OpenGeniRequestOptions = {},
+): Promise<WorkspaceUsageResponse> {
+  return await client.requestJson(
+    "GET",
+    `${workspacePath(workspaceId)}/usage/me`,
+    undefined,
+    usageAllowanceQuery(query),
+    options,
+  );
+}
+
+/** Every roster page for one period (follows `nextCursor`). */
+export async function getAllUsage(
+  client: UsageAllowanceRequestClient,
+  workspaceId: string,
+  query: Omit<GetUsageRequest, "cursor"> = {},
+  options: OpenGeniRequestOptions = {},
+): Promise<WorkspaceUsageResponse> {
+  const first = await getUsage(client, workspaceId, { limit: 200, ...query }, options);
+  const members = [...first.members];
+  let cursor = first.nextCursor;
+  // Bounded: a cursor that repeats would otherwise loop forever.
+  const seen = new Set<string>();
+  while (cursor && !seen.has(cursor)) {
+    seen.add(cursor);
+    const page = await getUsage(client, workspaceId, { limit: 200, ...query, cursor }, options);
+    members.push(...page.members);
+    cursor = page.nextCursor;
+  }
+  return { ...first, members, nextCursor: null };
+}

package/src/vault-types.ts

@@ -0,0 +1,293 @@
+// Vault wire types (hand-written mirrors of `@opengeni/contracts` vaults.ts).
+// SDK consumers do not need the contracts runtime; apps/web pins these
+// mirrors against the zod schemas in a type-parity test.
+import type { VaultPolicy } from "./types";
+
+export type { VaultPolicy };
+
+export type VaultOwnerKind = "user" | "workspace" | "organization" | "task";
+export type VaultSource = "opengeni" | "onepassword" | "host";
+export type VaultMode = "read_write" | "read_only";
+export type VaultSyncStatus = "ok" | "syncing" | "error" | "auth_expired" | "rate_limited";
+export type VaultItemType = "login" | "api_key" | "note" | "file" | "passkey";
+export type VaultFieldKind = "text" | "concealed" | "totp" | "file";
+
+export type VaultAvailability = {
+  /** null = every workspace in the organization. */
+  allowedWorkspaceIds: string[] | null;
+  allowPersonalWorkspaces: boolean;
+};
+
+export type VaultSummary = {
+  id: string;
+  workspaceId: string;
+  ownerKind: VaultOwnerKind;
+  ownerLabel: string;
+  rootSessionId: string | null;
+  name: string;
+  description: string | null;
+  source: VaultSource;
+  mode: VaultMode;
+  syncStatus: VaultSyncStatus;
+  syncErrorCode: string | null;
+  syncErrorMessage: string | null;
+  lastSyncedAt: string | null;
+  rateLimitedUntil: string | null;
+  providerConnectionId: string | null;
+  availability: VaultAvailability | null;
+  isDefault: boolean;
+  itemCount: number;
+  canWrite: boolean;
+  canManage: boolean;
+  generation: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type VaultItemReferences = {
+  primary: string | null;
+  otp: string | null;
+  byField: Record<string, string>;
+};
+
+export type VaultItemSummary = {
+  id: string;
+  vaultId: string;
+  type: VaultItemType;
+  name: string;
+  websites: string[];
+  username: string | null;
+  hasTotp: boolean;
+  hasPasskey: boolean;
+  expiresAt: string | null;
+  archivedAt: string | null;
+  lastUsedAt: string | null;
+  updatedAt: string;
+  references: VaultItemReferences;
+};
+
+export type VaultItemField = {
+  id: string;
+  name: string;
+  kind: VaultFieldKind;
+  position: number;
+  /** null for provider fields. */
+  currentVersion: number | null;
+  /** Plaintext only for kind "text"; null otherwise. */
+  value: string | null;
+  fileName: string | null;
+  fileSize: number | null;
+  reference: string;
+  updatedAt: string;
+};
+
+export type PasskeySummary = {
+  rpId: string;
+  userName: string | null;
+  credentialIdSuffix: string;
+  signCount: number;
+  leasedUntil: string | null;
+  lastUsedAt: string | null;
+};
+
+export type VaultItem = VaultItemSummary & {
+  fields: VaultItemField[];
+  passkey: PasskeySummary | null;
+  aliases: string[];
+  primaryFieldId: string | null;
+  createdBySubjectId: string | null;
+  createdAt: string;
+  generation: number;
+};
+
+export type VaultVersionCreatedByKind =
+  | "human"
+  | "agent"
+  | "api_key"
+  | "migration"
+  | "provider"
+  | "system";
+
+export type VaultFieldVersionMeta = {
+  version: number;
+  current: boolean;
+  createdAt: string;
+  createdByKind: VaultVersionCreatedByKind;
+  createdBySubjectId: string | null;
+};
+
+export type GeneratePasswordOptions = {
+  length?: number | undefined;
+  lowercase?: boolean | undefined;
+  uppercase?: boolean | undefined;
+  digits?: boolean | undefined;
+  symbols?: boolean | undefined;
+  symbolSet?: string | undefined;
+  excludeAmbiguous?: boolean | undefined;
+  requireEachClass?: boolean | undefined;
+};
+
+export type CreateVaultRequest = {
+  name: string;
+  description?: string | undefined;
+  ownerKind: "user" | "workspace" | "organization";
+  availability?: VaultAvailability | undefined;
+};
+
+export type UpdateVaultRequest = {
+  expectedGeneration: number;
+  name?: string | undefined;
+  description?: string | null | undefined;
+  availability?: VaultAvailability | undefined;
+};
+
+export type VaultFieldInput = {
+  fieldId?: string | undefined;
+  name: string;
+  kind?: VaultFieldKind | undefined;
+  value?: string | undefined;
+  generate?: GeneratePasswordOptions | undefined;
+  fromReference?: string | undefined;
+  fileBase64?: string | undefined;
+  fileName?: string | undefined;
+  restoreVersion?: number | undefined;
+  remove?: true | undefined;
+};
+
+export type CreateVaultItemRequest = {
+  type: VaultItemType;
+  name: string;
+  websites?: string[] | undefined;
+  expiresAt?: string | null | undefined;
+  fields: VaultFieldInput[];
+  primaryFieldName?: string | undefined;
+};
+
+export type UpdateVaultItemRequest = Partial<CreateVaultItemRequest> & {
+  expectedGeneration: number;
+};
+
+export type MoveVaultItemRequest = {
+  targetVaultId: string;
+  mode: "move" | "copy";
+  newName?: string | undefined;
+};
+
+export type RevealVaultFieldResponse = {
+  value: string;
+  encoding: "utf8" | "base64";
+  version: number | null;
+  totp: { code: string; periodSeconds: number; expiresAt: string } | null;
+};
+
+export type ListVaultItemsQuery = {
+  q?: string | undefined;
+  type?: VaultItemType | undefined;
+  includeArchived?: boolean | undefined;
+  cursor?: string | undefined;
+  limit?: number | undefined;
+};
+
+export type SessionSecretsVault = VaultSummary & { selected: boolean; selectable: boolean };
+
+export type SessionSecretsView = {
+  capabilityEnabled: boolean;
+  policy: VaultPolicy;
+  effectiveVaultIds: string[];
+  /** Nearest ancestor that narrowed, if any. */
+  narrowedBySessionId: string | null;
+  taskVault: VaultSummary | null;
+  taskItems: VaultItemSummary[];
+  reachableVaults: SessionSecretsVault[];
+};
+
+export type OnePasswordPlanTier = "family" | "teams" | "business";
+
+export type InstallOnePasswordRequest = {
+  token: string;
+  ownership: "user" | "workspace" | "organization";
+  planTier?: OnePasswordPlanTier | undefined;
+  label?: string | undefined;
+};
+
+export type ProviderVaultMeta = {
+  externalVaultId: string;
+  name: string;
+  itemCount: number | null;
+  linkedVaultId: string | null;
+};
+
+export type InstallOnePasswordResponse = {
+  connectionId: string;
+  accountName: string | null;
+  vaults: ProviderVaultMeta[];
+};
+
+/** A 1Password service account connected in a workspace. Never carries the token. */
+export type OnePasswordConnectionSummary = {
+  id: string;
+  /** Who can use the vaults linked through it. */
+  ownership: "user" | "workspace" | "organization";
+  /** Sign-in host from the token, for example "my.1password.com". */
+  accountName: string | null;
+  label: string | null;
+  planTier: OnePasswordPlanTier;
+  /** When the current token was last checked against 1Password. */
+  verifiedAt: string;
+  createdAt: string;
+  createdBySubjectId: string | null;
+  /** The caller can link vaults, replace the token and disconnect it. */
+  canManage: boolean;
+};
+
+/** A new token for an existing connection; its linked vaults keep working. */
+export type ReplaceOnePasswordTokenRequest = {
+  token: string;
+  planTier?: OnePasswordPlanTier | undefined;
+};
+
+export type DisconnectOnePasswordResponse = {
+  /** The Opengeni vaults that were unlinked. Nothing is deleted in 1Password. */
+  unlinkedVaultIds: string[];
+};
+
+export type LinkProviderVaultRequest = {
+  provider: "onepassword" | "host";
+  connectionId?: string | undefined;
+  externalVaultId: string;
+  ownerKind: "user" | "workspace" | "organization";
+  mode: VaultMode;
+  name?: string | undefined;
+  availability?: VaultAvailability | undefined;
+};
+
+export type CreateManagedProviderVaultRequest = {
+  name: string;
+  ownerKind: "user" | "workspace" | "organization";
+  groupId?: string | undefined;
+};
+
+export type VaultErrorCode =
+  | "vault_not_found"
+  | "vault_item_not_found"
+  | "vault_field_not_found"
+  | "vault_name_conflict"
+  | "vault_item_name_conflict"
+  | "vault_limit_reached"
+  | "vault_read_only"
+  | "vault_generation_conflict"
+  | "vault_permission_denied"
+  | "vault_reveal_requires_human"
+  | "vault_policy_outside_parent"
+  | "encryption_key_missing"
+  | "provider_auth_invalid"
+  | "provider_auth_expired"
+  | "provider_rate_limited"
+  | "provider_unavailable"
+  | "provider_conflict"
+  | "variable_sets_removed"
+  | "secret_save_forbidden"
+  | "invalid_secret_name"
+  | "secret_value_too_large"
+  | "human_auth_required"
+  | "secret_search_cursor_invalid";