@opengeni/sdk 1.0.2 → 1.2.0

package/dist/site.js

@@ -18,11 +18,12 @@ import {
   sanitizeOpenGeniSiteToolCallRequest,
   serveSiteHttp,
   siteSessionPath
-} from "./chunk-DUVIYER4.js";
+} from "./chunk-2ULNDOLD.js";
 import "./chunk-4SMEOV3P.js";
-import "./chunk-FG3OO5LM.js";
+import "./chunk-5AN2FLNC.js";
+import "./chunk-VPVMLM7Q.js";
 import "./chunk-APXVSSSY.js";
-import "./chunk-YIKA2QT4.js";
+import "./chunk-WIYAB33K.js";
 import "./chunk-NC57YMUO.js";
 import "./chunk-V6GIY62B.js";
 export {

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { WorkspaceTranscriptionPolicy } from "./transcription.js";
+export type { InsightsUsageRange, InsightsUsageGroupBy, InsightsUsagePayer, InsightsUsageSource, InsightsUsageTokens, InsightsUsageClassMicros, InsightsUsageMeasures, InsightsUsageScope, InsightsUsageGroup, InsightsUsageSeriesPoint, InsightsUsageFacets, InsightsUsageResponse, InsightsCall, InsightsCallsResponse, InsightsUsageWindowOptions, WorkspaceInsightsUsageOptions, OrganizationInsightsUsageOptions, WorkspaceInsightsCallsOptions, OrganizationInsightsCallsOptions, InsightsCallsScope, } from "./insights-usage.js";
 export type { ClaudeSubscriptionOAuthStartResponse, ClaudeSubscriptionOAuthCompleteRequest, ClaudeSubscriptionOAuthCompleteResponse, } from "@opengeni/contracts";
 export type { SessionMessageSearchRequest, SessionMessageSearchMatch, SessionMessageSearchResponse, SessionMessagePreview, SessionMessagePreviewReference, } from "./session-message-search.js";
 export type BundledSkillId = "builtin:opengeni-help" | "builtin:opengeni-client" | "builtin:opengeni-visualize" | "builtin:document-parsing" | "builtin:opengeni-skills" | "builtin:opengeni-projects" | "builtin:opengeni-schedules" | "builtin:opengeni-documents" | "builtin:opengeni-spreadsheets" | "builtin:opengeni-presentations" | "builtin:opengeni-sites" | "builtin:opengeni-video-generation";
@@ -2736,6 +2737,8 @@ export type ClientModel = {
     label: string;
     /** Optional curated compact label for dense UI (e.g. mobile composer). */
     shortLabel?: string | undefined;
+    /** Optional HTTPS maker logo supplied by the model catalog. */
+    logoUrl?: string | undefined;
     /** Provider id (e.g. `openai`, `azure`, or a registry provider id). */
     provider: string;
     providerLabel: string;
@@ -2775,6 +2778,7 @@ export type ModelCredentialReadinessV1 = {
 };
 export type WorkspaceModelCatalogModel = ClientModel & {
     credentialReadiness: ModelCredentialReadinessV1;
+    creditFunding?: "promotional" | "general" | "unavailable" | undefined;
     /** Exact workspace-policy verdict without exposing provider identity. */
     policyAllowed?: boolean | undefined;
     availability: ModelAvailabilityV1;
@@ -4976,7 +4980,7 @@ export type ScheduledTaskRunAwaitingHuman = {
 };
 export type ScheduledTaskAdmissionRefusal = {
     version: 1;
-    reason: "scheduled_authority_unavailable" | "machine_target_unavailable" | "machine_enrollment_inactive" | "variable_set_unavailable" | "rig_version_unavailable" | "insufficient_credits" | "monthly_model_cost_limit" | "monthly_agent_run_limit" | (string & {});
+    reason: "scheduled_authority_unavailable" | "machine_target_unavailable" | "machine_enrollment_inactive" | "variable_set_unavailable" | "rig_version_unavailable" | "scheduled_model_unavailable" | "insufficient_credits" | "monthly_model_cost_limit" | "monthly_agent_run_limit" | (string & {});
     retryable: boolean;
 };
 export type ScheduledTaskAccessFailureReason = "missing_connection" | "expired" | "insufficient_scope" | "refresh_failed" | "personal_authority_unavailable" | "unsupported_auth" | "resource_scope_unavailable";
@@ -6651,11 +6655,21 @@ export type CreateGitHubAppManifestResponse = {
 };
 export type BillingMode = "disabled" | "stripe";
 export type EntitlementsMode = "none" | "static" | "managed";
+export type PromotionalCreditScope = {
+    label: string;
+    eligibleModelIds: string[];
+};
+export type PromotionalCreditBalance = PromotionalCreditScope & {
+    grantId: string;
+    remainingMicros: number;
+};
 export type BillingBalance = {
     accountId: string;
     balanceMicros: number;
     currency: "usd";
     updatedAt: string;
+    generalBalanceMicros?: number | undefined;
+    promotionalCredits?: PromotionalCreditBalance[] | undefined;
 };
 export declare const KNOWN_USAGE_EVENT_TYPES: readonly ["agent_run.created", "agent_run.completed", "model.tokens", "model.cost", "file.uploaded", "file.deleted", "document.indexed", "scheduled_task.fired", "knowledge_source_sync.fired", "knowledge_source_sync.completed", "knowledge_source_sync.items", "knowledge_source_sync.bytes", "api_key.request", "sandbox.warm_seconds", "sandbox.warm_cost"];
 export type KnownUsageEventType = (typeof KNOWN_USAGE_EVENT_TYPES)[number];
@@ -6948,6 +6962,7 @@ export type CreateCheckoutResponse = {
     url: string;
     /** The credits this checkout grants once it completes. */
     amountUsd?: number | undefined;
+    promotionalScope?: PromotionalCreditScope | undefined;
 };
 /** Where one checkout stands, and whether its credits reached the balance. */
 export type BillingCheckoutStatus = {
@@ -6959,6 +6974,7 @@ export type BillingCheckoutStatus = {
         currency: "usd";
         /** True when a coupon covered the whole checkout, so nothing was charged. */
         free: boolean;
+        promotionalScope?: PromotionalCreditScope | undefined;
     };
     balance: BillingBalance | null;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Framework-agnostic TypeScript SDK for the OpenGeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {
@@ -58,6 +58,10 @@
       "types": "./dist/usage-allowances.d.ts",
       "import": "./dist/usage-allowances.js"
     },
+    "./insights-usage": {
+      "types": "./dist/insights-usage.d.ts",
+      "import": "./dist/insights-usage.js"
+    },
     "./workspace-integrations": {
       "types": "./dist/workspace-integrations.d.ts",
       "import": "./dist/workspace-integrations.js"
@@ -165,7 +169,8 @@
     "./session-list-entries": {
       "types": "./dist/session-list-entries.d.ts",
       "import": "./dist/session-list-entries.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public",
@@ -177,8 +182,8 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/connect": "1.0.2",
-    "@opengeni/contracts": "1.0.2"
+    "@opengeni/connect": "1.2.0",
+    "@opengeni/contracts": "1.2.0"
   },
   "engines": {
     "node": ">=18"

package/src/artifact-catalog.ts

@@ -16,6 +16,8 @@ export type ArtifactCatalogItem = {
   createdAt: string;
   updatedAt: string;
   status: "active" | "archived";
+  /** Shared workspace pin; absent on older servers. Never grants content access. */
+  pinned?: boolean;
   /** Present only when the viewer can read this session. */
   sourceSessionId?: string;
   versionId?: string;
@@ -39,3 +41,9 @@ export type ArtifactCatalogListResponse = {
   items: ArtifactCatalogItem[];
   nextCursor: string | null;
 };
+
+export type ArtifactPinResponse = {
+  kind: ArtifactCatalogKind;
+  artifactId: string;
+  pinned: boolean;
+};

package/src/chat/opengeni.ts

@@ -76,11 +76,12 @@ export class OpenGeni {
   constructor(options: OpenGeniOptions) {
     if (!options.apiKey) throw new TypeError("Opengeni requires an apiKey.");
     this.client = new OpenGeniClient({
-      baseUrl: options.baseUrl ?? DEFAULT_OPENGENI_BASE_URL,
+      // An empty value (a blank `OPENGENI_API_BASE_URL=` in .env) means the default.
+      baseUrl: options.baseUrl?.trim() || DEFAULT_OPENGENI_BASE_URL,
       apiKey: options.apiKey,
       ...(options.fetch ? { fetch: options.fetch } : {}),
     });
-    this.organizationId = options.organizationId ?? "";
+    this.organizationId = options.organizationId?.trim() ?? "";
     this.source = options.source ?? DEFAULT_CHAT_SOURCE;
     this.resolveWorkspaceId = createWorkspaceIdResolver(this.client, {
       organizationId: () => this.resolveOrganizationId(),

package/src/client.ts

@@ -5,7 +5,22 @@ import type {
   ClaudeSubscriptionSetupTokenRequest,
   SubscriptionPoolSettings,
 } from "@opengeni/contracts";
-import type { ArtifactCatalogListOptions, ArtifactCatalogListResponse } from "./artifact-catalog";
+import {
+  insightsUsageQueryString,
+  type WorkspaceInsightsUsageOptions,
+  type OrganizationInsightsUsageOptions,
+  type WorkspaceInsightsCallsOptions,
+  type OrganizationInsightsCallsOptions,
+  type InsightsCallsScope,
+  type InsightsUsageResponse,
+  type InsightsCallsResponse,
+} from "./insights-usage";
+import type {
+  ArtifactCatalogKind,
+  ArtifactCatalogListOptions,
+  ArtifactCatalogListResponse,
+  ArtifactPinResponse,
+} from "./artifact-catalog";
 import type {
   SessionMessageSearchRequest,
   SessionMessageSearchResponse,
@@ -7589,6 +7604,23 @@ export class OpenGeniClient {
     );
   }
 
+  /** Idempotently set a workspace-shared pin; refresh the catalog after completion. */
+  async updateArtifactPin(
+    workspaceId: string,
+    kind: ArtifactCatalogKind,
+    artifactId: string,
+    pinned: boolean,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<ArtifactPinResponse> {
+    return this.requestJson<ArtifactPinResponse>(
+      "PUT",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/artifact-catalog/${encodeURIComponent(kind)}/${encodeURIComponent(artifactId)}/pin`,
+      { pinned },
+      undefined,
+      options,
+    );
+  }
+
   async listWorkspaceArtifacts(
     workspaceId: string,
     options: WorkspaceArtifactListOptions & { signal?: AbortSignal } = {},
@@ -8867,6 +8899,65 @@ export class OpenGeniClient {
     );
   }
 
+  /** Shared usage under the existing workspace access gate. */
+  async getWorkspaceInsightsUsage(
+    workspaceId: string,
+    options: WorkspaceInsightsUsageOptions = {},
+    requestOptions: OpenGeniRequestOptions = {},
+  ): Promise<InsightsUsageResponse> {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/insights/usage${insightsUsageQueryString(options)}`,
+      undefined,
+      {},
+      requestOptions,
+    );
+  }
+
+  /** Shared usage under the existing organization access gate. */
+  async getOrganizationInsightsUsage(
+    accountId: string,
+    options: OrganizationInsightsUsageOptions = {},
+    requestOptions: OpenGeniRequestOptions = {},
+  ): Promise<InsightsUsageResponse> {
+    return await this.requestJson(
+      "GET",
+      `/v1/organizations/${encodeURIComponent(accountId)}/insights/usage${insightsUsageQueryString(options)}`,
+      undefined,
+      {},
+      requestOptions,
+    );
+  }
+
+  /** Visible calls only; a filter never grants access to hidden call facts. */
+  async listInsightsCalls(
+    scope: Extract<InsightsCallsScope, { kind: "workspace" }>,
+    options?: WorkspaceInsightsCallsOptions,
+    requestOptions?: OpenGeniRequestOptions,
+  ): Promise<InsightsCallsResponse>;
+  async listInsightsCalls(
+    scope: Extract<InsightsCallsScope, { kind: "organization" }>,
+    options?: OrganizationInsightsCallsOptions,
+    requestOptions?: OpenGeniRequestOptions,
+  ): Promise<InsightsCallsResponse>;
+  async listInsightsCalls(
+    scope: InsightsCallsScope,
+    options: OrganizationInsightsCallsOptions = {},
+    requestOptions: OpenGeniRequestOptions = {},
+  ): Promise<InsightsCallsResponse> {
+    const path =
+      scope.kind === "workspace"
+        ? `/v1/workspaces/${encodeURIComponent(scope.workspaceId)}/insights/calls`
+        : `/v1/organizations/${encodeURIComponent(scope.accountId)}/insights/calls`;
+    return await this.requestJson(
+      "GET",
+      `${path}${insightsUsageQueryString(options)}`,
+      undefined,
+      {},
+      requestOptions,
+    );
+  }
+
   async getBillingEntitlements(
     options: { accountId?: string } = {},
   ): Promise<BillingEntitlementsResponse> {

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
   ClaudeSubscriptionAccountsResponse,
 } from "@opengeni/contracts";
 export type {
+  ArtifactPinResponse,
   ArtifactCatalogKind,
   ArtifactCatalogItem,
   ArtifactCatalogListOptions,
@@ -621,6 +622,8 @@ export type {
   AgentToolCallOutputPayload,
   ApiKey,
   BillingBalance,
+  PromotionalCreditScope,
+  PromotionalCreditBalance,
   BillingEntitlementsResponse,
   BillingMode,
   BillingSummary,

package/src/insights-usage.ts

@@ -0,0 +1,61 @@
+// Type-only references keep this opt-in SDK leaf free of zod/root contracts.
+import type {
+  OrganizationInsightsUsageQueryInput,
+  OrganizationInsightsCallsQueryInput,
+  InsightsUsageRange,
+  InsightsUsagePayer,
+  InsightsUsageSource,
+} from "@opengeni/contracts/insights-usage";
+
+export type {
+  InsightsUsageRange,
+  InsightsUsageGroupBy,
+  InsightsUsagePayer,
+  InsightsUsageSource,
+  InsightsUsageTokens,
+  InsightsUsageClassMicros,
+  InsightsUsageMeasures,
+  InsightsUsageScope,
+  InsightsUsageGroup,
+  InsightsUsageSeriesPoint,
+  InsightsUsageFacets,
+  InsightsUsageResponse,
+  InsightsCall,
+  InsightsCallsResponse,
+} from "@opengeni/contracts/insights-usage";
+
+/** Custom selections require both inclusive UTC calendar days. */
+export type InsightsUsageWindowOptions =
+  | { range?: Exclude<InsightsUsageRange, "custom">; from?: never; to?: never }
+  | { range: "custom"; from: string; to: string };
+
+type FilterOptions<T> = Omit<T, "range" | "from" | "to" | "limit" | "payer" | "source"> &
+  InsightsUsageWindowOptions & {
+    limit?: number;
+    payer?: InsightsUsagePayer | InsightsUsagePayer[];
+    source?: InsightsUsageSource | InsightsUsageSource[];
+  };
+
+export type OrganizationInsightsUsageOptions = FilterOptions<
+  Omit<OrganizationInsightsUsageQueryInput, "seriesGroups">
+> & { seriesGroups?: boolean };
+/** workspaceId is intersected with the path workspace by the existing server gate. */
+export type WorkspaceInsightsUsageOptions = OrganizationInsightsUsageOptions;
+export type OrganizationInsightsCallsOptions = FilterOptions<OrganizationInsightsCallsQueryInput>;
+export type WorkspaceInsightsCallsOptions = OrganizationInsightsCallsOptions;
+export type InsightsCallsScope =
+  | { kind: "workspace"; workspaceId: string }
+  | { kind: "organization"; accountId: string };
+
+/** Arrays repeat; comma strings, false and opaque values round-trip unchanged. */
+export function insightsUsageQueryString(
+  options: OrganizationInsightsUsageOptions | OrganizationInsightsCallsOptions,
+): string {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(options)) {
+    if (value === undefined) continue;
+    for (const item of Array.isArray(value) ? value : [value]) params.append(key, String(item));
+  }
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}

package/src/model-display.ts

@@ -3,6 +3,7 @@ export {
   humanizeModelSlug,
   isRawModelLabel,
   modelDisplayName,
+  modelLogoUrl,
   modelSlug,
   modelVendor,
   type ModelDisplayInput,