@opengeni/sdk 0.52.1 → 1.0.0

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/workspace-artifacts.ts

@@ -1,3 +1,15 @@
+import type { ToolGatewayIdentity } from "./types";
+
+export type WorkspaceArtifactSourceFile = {
+  path: string;
+  content: string;
+};
+
+export type WorkspaceArtifactSourceBundle = {
+  entrypoint: string;
+  files: WorkspaceArtifactSourceFile[];
+};
+
 export type WorkspaceArtifactVersion = {
   id: string;
   accountId: string;
@@ -5,8 +17,11 @@ export type WorkspaceArtifactVersion = {
   artifactId: string;
   revision: number;
   contentType: "text/html";
-  contentSha256: string;
+  contentSha256: string | null;
   sizeBytes: number;
+  sourceSha256: string | null;
+  sourceSizeBytes: number | null;
+  requestedTools: ToolGatewayIdentity[];
   sourceSessionId: string | null;
   sourceTurnId: string | null;
   sourceAttemptId: string | null;
@@ -34,7 +49,7 @@ export type WorkspaceArtifactEvent = {
   accountId: string;
   workspaceId: string;
   artifactId: string;
-  type: "published" | "rolled_back";
+  type: "published" | "rolled_back" | "archived" | "restored";
   fromVersionId: string | null;
   toVersionId: string;
   sourceSessionId: string | null;
@@ -46,7 +61,12 @@ export type WorkspaceArtifactEvent = {
   createdAt: string;
 };
 
-export type WorkspaceArtifactListOptions = { limit?: number; cursor?: string };
+export type WorkspaceArtifactListOptions = {
+  sourceSessionId?: string;
+  limit?: number;
+  cursor?: string;
+  status?: WorkspaceArtifact["status"];
+};
 export type WorkspaceArtifactListResponse = {
   artifacts: WorkspaceArtifact[];
   nextCursor: string | null;
@@ -63,8 +83,10 @@ export type WorkspaceArtifactContentResponse = {
   artifactId: string;
   versionId: string;
   contentType: "text/html";
-  contentSha256: string;
+  contentSha256: string | null;
   html: string;
+  source: WorkspaceArtifactSourceBundle;
+  requestedTools: ToolGatewayIdentity[];
 };
 export type WorkspaceArtifactMutationResponse = {
   artifact: WorkspaceArtifact;
@@ -76,13 +98,19 @@ export type CreateWorkspaceArtifactRequest = {
   slug?: string;
   title: string;
   description?: string | null;
-  html: string;
+  html?: string;
+  uploadId?: string;
+  source?: WorkspaceArtifactSourceBundle;
+  requestedTools?: ToolGatewayIdentity[];
   idempotencyKey: string;
 };
 export type PublishWorkspaceArtifactVersionRequest = {
   title?: string;
   description?: string | null;
-  html: string;
+  html?: string;
+  uploadId?: string;
+  source?: WorkspaceArtifactSourceBundle;
+  requestedTools?: ToolGatewayIdentity[];
   expectedCurrentVersionId: string;
   idempotencyKey: string;
 };
@@ -92,3 +120,9 @@ export type RollbackWorkspaceArtifactRequest = {
   reason: string;
   idempotencyKey: string;
 };
+export type SetWorkspaceArtifactStatusRequest = {
+  status: "active" | "archived";
+  expectedCurrentVersionId: string;
+  reason: string;
+  idempotencyKey: string;
+};

package/src/workspace-instruction-policies.ts

@@ -5,11 +5,12 @@ export type WorkspaceInstructionPolicyScope = "global" | "role";
 export type WorkspaceInstructionPolicyProvenanceSource =
   | "human"
   | "onboarding"
+  | "agent_learning"
   | "knowledge_proposal"
   | "legacy_import";
 export type WorkspaceInstructionPolicyDraftProvenanceSource = Exclude<
   WorkspaceInstructionPolicyProvenanceSource,
-  "legacy_import"
+  "legacy_import" | "agent_learning"
 >;
 export type WorkspaceInstructionPolicyActivationType = "activate" | "rollback";
 
@@ -53,6 +54,12 @@ export type WorkspaceInstructionPolicyHead = WorkspaceInstructionPolicyTarget &
   activatedAt: string;
 };
 
+export type WorkspaceInstructionPolicyInactiveHead = WorkspaceInstructionPolicyTarget & {
+  workspaceId: string;
+  activationVersion: number;
+  deactivatedAt: string;
+};
+
 export type WorkspaceInstructionPolicyActivationEvent = WorkspaceInstructionPolicyTarget & {
   id: string;
   operationId: string;
@@ -67,6 +74,19 @@ export type WorkspaceInstructionPolicyActivationEvent = WorkspaceInstructionPoli
   createdAt: string;
 };
 
+export type WorkspaceInstructionPolicyDeactivationEvent = WorkspaceInstructionPolicyTarget & {
+  id: string;
+  operationId: string;
+  accountId: string;
+  workspaceId: string;
+  type: "automatic_deactivate";
+  activationVersion: number;
+  oldRevision: WorkspaceInstructionPolicyRevisionIdentity;
+  actorSubjectId: string;
+  reason: string;
+  createdAt: string;
+};
+
 export type CreateWorkspaceInstructionPolicyDraftRequest = WorkspaceInstructionPolicyTarget & {
   operationId?: string;
   content: string;
@@ -91,7 +111,12 @@ export type WorkspaceInstructionPolicyListOptions = {
 export type WorkspaceInstructionPolicyListResponse = {
   revisions: WorkspaceInstructionPolicyRevision[];
   activeHeads: WorkspaceInstructionPolicyHead[];
+  /** Additive current inactive target boundaries; absent on pre-controller servers. */
+  inactiveHeads?: WorkspaceInstructionPolicyInactiveHead[];
+  inactiveHeadsTruncated?: boolean;
   activationEvents: WorkspaceInstructionPolicyActivationEvent[];
+  /** Additive lifecycle history; absent on pre-controller servers. */
+  deactivationEvents?: WorkspaceInstructionPolicyDeactivationEvent[];
   nextAfterRevision: number | null;
 };