@cadenya/cadenya 0.40.0

package/src/internal/utils/path.ts

@@ -0,0 +1,88 @@
+import { CadenyaError } from '../../core/error';
+
+/**
+ * Percent-encode everything that isn't safe to have in a path without encoding safe chars.
+ *
+ * Taken from https://datatracker.ietf.org/doc/html/rfc3986#section-3.3:
+ * > unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
+ * > sub-delims  = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+ * > pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
+ */
+export function encodeURIPath(str: string) {
+  return str.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
+}
+
+const EMPTY = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.create(null));
+
+export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
+  function path(statics: readonly string[], ...params: readonly unknown[]): string {
+    // If there are no params, no processing is needed.
+    if (statics.length === 1) return statics[0]!;
+
+    let postPath = false;
+    const invalidSegments = [];
+    const path = statics.reduce((previousValue, currentValue, index) => {
+      if (/[?#]/.test(currentValue)) {
+        postPath = true;
+      }
+      const value = params[index];
+      let encoded = (postPath ? encodeURIComponent : pathEncoder)('' + value);
+      if (
+        index !== params.length &&
+        (value == null ||
+          (typeof value === 'object' &&
+            // handle values from other realms
+            value.toString ===
+              Object.getPrototypeOf(Object.getPrototypeOf((value as any).hasOwnProperty ?? EMPTY) ?? EMPTY)
+                ?.toString))
+      ) {
+        encoded = value + '';
+        invalidSegments.push({
+          start: previousValue.length + currentValue.length,
+          length: encoded.length,
+          error: `Value of type ${Object.prototype.toString
+            .call(value)
+            .slice(8, -1)} is not a valid path parameter`,
+        });
+      }
+      return previousValue + currentValue + (index === params.length ? '' : encoded);
+    }, '');
+
+    const pathOnly = path.split(/[?#]/, 1)[0]!;
+    const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
+    let match;
+
+    // Find all invalid segments
+    while ((match = invalidSegmentPattern.exec(pathOnly)) !== null) {
+      invalidSegments.push({
+        start: match.index,
+        length: match[0].length,
+        error: `Value "${match[0]}" can\'t be safely passed as a path parameter`,
+      });
+    }
+
+    invalidSegments.sort((a, b) => a.start - b.start);
+
+    if (invalidSegments.length > 0) {
+      let lastEnd = 0;
+      const underline = invalidSegments.reduce((acc, segment) => {
+        const spaces = ' '.repeat(segment.start - lastEnd);
+        const arrows = '^'.repeat(segment.length);
+        lastEnd = segment.start + segment.length;
+        return acc + spaces + arrows;
+      }, '');
+
+      throw new CadenyaError(
+        `Path parameters result in path with invalid segments:\n${invalidSegments
+          .map((e) => e.error)
+          .join('\n')}\n${path}\n${underline}`,
+      );
+    }
+
+    return path;
+  };
+
+/**
+ * URI-encodes path params and ensures no unsafe /./ or /../ path segments are introduced.
+ */
+export const path = /* @__PURE__ */ createPathTagFunction(encodeURIPath);

package/src/internal/utils/query.ts

@@ -0,0 +1,23 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { CadenyaError } from '../../core/error';
+
+/**
+ * Basic re-implementation of `qs.stringify` for primitive types.
+ */
+export function stringifyQuery(query: object | Record<string, unknown>) {
+  return Object.entries(query)
+    .filter(([_, value]) => typeof value !== 'undefined')
+    .map(([key, value]) => {
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+      }
+      if (value === null) {
+        return `${encodeURIComponent(key)}=`;
+      }
+      throw new CadenyaError(
+        `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
+      );
+    })
+    .join('&');
+}

package/src/internal/utils/sleep.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

package/src/internal/utils/uuid.ts

@@ -0,0 +1,17 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+/**
+ * https://stackoverflow.com/a/2117523
+ */
+export let uuid4 = function () {
+  const { crypto } = globalThis as any;
+  if (crypto?.randomUUID) {
+    uuid4 = crypto.randomUUID.bind(crypto);
+    return crypto.randomUUID();
+  }
+  const u8 = new Uint8Array(1);
+  const randomByte = crypto ? () => crypto.getRandomValues(u8)[0]! : () => (Math.random() * 0xff) & 0xff;
+  return '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, (c) =>
+    (+c ^ (randomByte() & (15 >> (+c / 4)))).toString(16),
+  );
+};

package/src/internal/utils/values.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { CadenyaError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+export let isArray = (val: unknown): val is unknown[] => ((isArray = Array.isArray), isArray(val));
+export let isReadonlyArray = isArray as (val: unknown) => val is readonly unknown[];
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new CadenyaError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new CadenyaError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new CadenyaError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new CadenyaError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new CadenyaError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,9 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';
+export * from './utils/query';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/account.ts

@@ -0,0 +1,93 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as Shared from './shared';
+import * as WorkspacesAPI from './workspaces';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+/**
+ * AccountService manages account-level operations.
+ *  Accounts are the top-level organizational unit in the system.
+ *  All operations are scoped to the authenticated account determined by the JWT token.
+ *
+ *  Authentication: Bearer token (JWT)
+ *  Scope: Account-level operations
+ */
+export class AccountResource extends APIResource {
+  /**
+   * Retrieves the current account for the token accessing the API. Useful to check
+   * if the credentials are valid.
+   */
+  retrieve(options?: RequestOptions): APIPromise<Account> {
+    return this._client.get('/v1/account', options);
+  }
+}
+
+export interface Account {
+  /**
+   * AccountResourceMetadata is used to represent a resource that is associated to an
+   * account but not to a workspace.
+   */
+  metadata: Shared.AccountResourceMetadata;
+
+  spec: AccountSpec;
+}
+
+export interface AccountSpec {
+  billingEmail?: string;
+
+  description?: string;
+
+  domain?: string;
+
+  workspaces?: Array<WorkspacesAPI.Workspace>;
+}
+
+/**
+ * Profile represents a human user at the account level. Profiles are
+ * account-scoped resources that can be associated with multiple workspaces through
+ * the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
+ */
+export interface Profile {
+  /**
+   * AccountResourceMetadata is used to represent a resource that is associated to an
+   * account but not to a workspace.
+   */
+  metadata: Shared.AccountResourceMetadata;
+
+  /**
+   * ProfileSpec contains the profile-specific fields
+   */
+  spec: ProfileSpec;
+}
+
+/**
+ * ProfileSpec contains the profile-specific fields
+ */
+export interface ProfileSpec {
+  /**
+   * Type is the type of profile. User's are humans, API keys are computers. You know
+   * the deal.
+   */
+  type: 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM';
+
+  /**
+   * Email address of the user (required, unique per account)
+   */
+  email?: string;
+
+  /**
+   * Display name for the user (e.g., "Bobby Tables")
+   */
+  name?: string;
+}
+
+export declare namespace AccountResource {
+  export {
+    type Account as Account,
+    type AccountSpec as AccountSpec,
+    type Profile as Profile,
+    type ProfileSpec as ProfileSpec,
+  };
+}

package/src/resources/agents/agents.ts

@@ -0,0 +1,296 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as AccountAPI from '../account';
+import * as Shared from '../shared';
+import * as VariationsAPI from './variations';
+import {
+  AgentVariation,
+  AgentVariationInfo,
+  AgentVariationSpec,
+  AgentVariationSpecAgentDocument,
+  AgentVariationSpecAgentTool,
+  AgentVariationSpecConstraints,
+  AgentVariationSpecModelConfig,
+  AgentVariationSpecToolSelection,
+  AgentVariationsCursorPagination,
+  ToolSelectionAssignedTools,
+  ToolSelectionAutoDiscovery,
+  VariationCreateParams,
+  VariationDeleteParams,
+  VariationListParams,
+  VariationRetrieveParams,
+  VariationUpdateParams,
+  Variations,
+} from './variations';
+import * as WebhookDeliveriesAPI from './webhook-deliveries';
+import {
+  WebhookDeliveries,
+  WebhookDeliveriesCursorPagination,
+  WebhookDelivery,
+  WebhookDeliveryData,
+  WebhookDeliveryListParams,
+} from './webhook-deliveries';
+import { APIPromise } from '../../core/api-promise';
+import { CursorPagination, type CursorPaginationParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * AgentService manages AI agents at the WORKSPACE level.
+ *  Agents are workspace-scoped resources that define AI behavior and tool access.
+ *  All operations are implicitly scoped to the workspace determined by the JWT token.
+ *
+ *  Authentication: Bearer token (JWT)
+ *  Scope: Workspace-level operations
+ */
+export class Agents extends APIResource {
+  variations: VariationsAPI.Variations = new VariationsAPI.Variations(this._client);
+  webhookDeliveries: WebhookDeliveriesAPI.WebhookDeliveries = new WebhookDeliveriesAPI.WebhookDeliveries(
+    this._client,
+  );
+
+  /**
+   * Creates a new agent in the workspace
+   */
+  create(body: AgentCreateParams, options?: RequestOptions): APIPromise<Agent> {
+    return this._client.post('/v1/agents', { body, ...options });
+  }
+
+  /**
+   * Retrieves an agent by ID from the workspace
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<Agent> {
+    return this._client.get(path`/v1/agents/${id}`, options);
+  }
+
+  /**
+   * Updates an agent in the workspace
+   */
+  update(id: string, body: AgentUpdateParams, options?: RequestOptions): APIPromise<Agent> {
+    return this._client.patch(path`/v1/agents/${id}`, { body, ...options });
+  }
+
+  /**
+   * Lists all agents in the workspace
+   */
+  list(
+    query: AgentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AgentsCursorPagination, Agent> {
+    return this._client.getAPIList('/v1/agents', CursorPagination<Agent>, { query, ...options });
+  }
+
+  /**
+   * Deletes an agent from the workspace
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/agents/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type AgentsCursorPagination = CursorPagination<Agent>;
+
+/**
+ * Agent resource
+ */
+export interface Agent {
+  /**
+   * Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
+   */
+  metadata: Shared.ResourceMetadata;
+
+  /**
+   * Agent specification (user-provided configuration)
+   */
+  spec: AgentSpec;
+
+  /**
+   * AgentInfo contains simple information about an agent for display or quick
+   * reference
+   */
+  info?: AgentInfo;
+}
+
+/**
+ * AgentInfo contains simple information about an agent for display or quick
+ * reference
+ */
+export interface AgentInfo {
+  /**
+   * Profile represents a human user at the account level. Profiles are
+   * account-scoped resources that can be associated with multiple workspaces through
+   * the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
+   */
+  createdBy?: AccountAPI.Profile;
+
+  variationCount?: number;
+}
+
+/**
+ * Agent specification (user-provided configuration)
+ */
+export interface AgentSpec {
+  /**
+   * Status of the agent
+   */
+  status:
+    | 'AGENT_STATUS_UNSPECIFIED'
+    | 'AGENT_STATUS_DRAFT'
+    | 'AGENT_STATUS_PUBLISHED'
+    | 'AGENT_STATUS_ARCHIVED';
+
+  /**
+   * Controls how variations are automatically selected when creating objectives
+   * Defaults to RANDOM when unspecified
+   */
+  variationSelectionMode:
+    | 'VARIATION_SELECTION_MODE_UNSPECIFIED'
+    | 'VARIATION_SELECTION_MODE_RANDOM'
+    | 'VARIATION_SELECTION_MODE_WEIGHTED';
+
+  /**
+   * Description of the agent's purpose
+   */
+  description?: string;
+
+  /**
+   * The generated secret that will sign all webhooks that are sent to your
+   * configured Webhook URL. Formatted as "wh_asdf1234" per the
+   * https://www.standardwebhooks.com/ format.
+   */
+  webhookEventsHmacSecret?: string;
+
+  /**
+   * The URL that Cadenya will send events for any objective assigned to the agent.
+   */
+  webhookEventsUrl?: string;
+}
+
+export interface Page {
+  nextCursor?: string;
+
+  total?: number;
+}
+
+export interface AgentCreateParams {
+  /**
+   * CreateResourceMetadata contains the user-provided fields for creating a
+   * workspace-scoped resource. Read-only fields (id, account_id, workspace_id,
+   * profile_id, created_at) are excluded since they are set by the server.
+   */
+  metadata: Shared.CreateResourceMetadata;
+
+  /**
+   * Agent specification (user-provided configuration)
+   */
+  spec: AgentSpec;
+
+  /**
+   * Create agent variation request
+   */
+  defaultVariation?: AgentCreateParams.DefaultVariation;
+}
+
+export namespace AgentCreateParams {
+  /**
+   * Create agent variation request
+   */
+  export interface DefaultVariation {
+    /**
+     * CreateResourceMetadata contains the user-provided fields for creating a
+     * workspace-scoped resource. Read-only fields (id, account_id, workspace_id,
+     * profile_id, created_at) are excluded since they are set by the server.
+     */
+    metadata: Shared.CreateResourceMetadata;
+
+    /**
+     * AgentVariationSpec defines the operational configuration for a variation
+     */
+    spec: VariationsAPI.AgentVariationSpec;
+  }
+}
+
+export interface AgentUpdateParams {
+  /**
+   * UpdateResourceMetadata contains the user-provided fields for updating a
+   * workspace-scoped resource. Read-only fields (id, account_id, workspace_id,
+   * profile_id, created_at) are excluded since they are set by the server.
+   */
+  metadata?: Shared.UpdateResourceMetadata;
+
+  /**
+   * Agent specification (user-provided configuration)
+   */
+  spec?: AgentSpec;
+
+  /**
+   * Fields to update
+   */
+  updateMask?: string;
+}
+
+export interface AgentListParams extends CursorPaginationParams {
+  /**
+   * When set to true you may use more of your alloted API rate-limit
+   */
+  includeInfo?: boolean;
+
+  /**
+   * Filter expression (query param: prefix)
+   */
+  prefix?: string;
+
+  /**
+   * Sort order for results (asc or desc by creation time)
+   */
+  sortOrder?: string;
+}
+
+Agents.Variations = Variations;
+Agents.WebhookDeliveries = WebhookDeliveries;
+
+export declare namespace Agents {
+  export {
+    type Agent as Agent,
+    type AgentInfo as AgentInfo,
+    type AgentSpec as AgentSpec,
+    type Page as Page,
+    type AgentsCursorPagination as AgentsCursorPagination,
+    type AgentCreateParams as AgentCreateParams,
+    type AgentUpdateParams as AgentUpdateParams,
+    type AgentListParams as AgentListParams,
+  };
+
+  export {
+    Variations as Variations,
+    type AgentVariation as AgentVariation,
+    type AgentVariationInfo as AgentVariationInfo,
+    type AgentVariationSpec as AgentVariationSpec,
+    type AgentVariationSpecAgentDocument as AgentVariationSpecAgentDocument,
+    type AgentVariationSpecAgentTool as AgentVariationSpecAgentTool,
+    type AgentVariationSpecConstraints as AgentVariationSpecConstraints,
+    type AgentVariationSpecModelConfig as AgentVariationSpecModelConfig,
+    type AgentVariationSpecToolSelection as AgentVariationSpecToolSelection,
+    type ToolSelectionAssignedTools as ToolSelectionAssignedTools,
+    type ToolSelectionAutoDiscovery as ToolSelectionAutoDiscovery,
+    type AgentVariationsCursorPagination as AgentVariationsCursorPagination,
+    type VariationCreateParams as VariationCreateParams,
+    type VariationRetrieveParams as VariationRetrieveParams,
+    type VariationUpdateParams as VariationUpdateParams,
+    type VariationListParams as VariationListParams,
+    type VariationDeleteParams as VariationDeleteParams,
+  };
+
+  export {
+    WebhookDeliveries as WebhookDeliveries,
+    type WebhookDelivery as WebhookDelivery,
+    type WebhookDeliveryData as WebhookDeliveryData,
+    type WebhookDeliveriesCursorPagination as WebhookDeliveriesCursorPagination,
+    type WebhookDeliveryListParams as WebhookDeliveryListParams,
+  };
+}

package/src/resources/agents/index.ts

@@ -0,0 +1,39 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Agents,
+  type Agent,
+  type AgentInfo,
+  type AgentSpec,
+  type Page,
+  type AgentCreateParams,
+  type AgentUpdateParams,
+  type AgentListParams,
+  type AgentsCursorPagination,
+} from './agents';
+export {
+  Variations,
+  type AgentVariation,
+  type AgentVariationInfo,
+  type AgentVariationSpec,
+  type AgentVariationSpecAgentDocument,
+  type AgentVariationSpecAgentTool,
+  type AgentVariationSpecConstraints,
+  type AgentVariationSpecModelConfig,
+  type AgentVariationSpecToolSelection,
+  type ToolSelectionAssignedTools,
+  type ToolSelectionAutoDiscovery,
+  type VariationCreateParams,
+  type VariationRetrieveParams,
+  type VariationUpdateParams,
+  type VariationListParams,
+  type VariationDeleteParams,
+  type AgentVariationsCursorPagination,
+} from './variations';
+export {
+  WebhookDeliveries,
+  type WebhookDelivery,
+  type WebhookDeliveryData,
+  type WebhookDeliveryListParams,
+  type WebhookDeliveriesCursorPagination,
+} from './webhook-deliveries';