@nebula-ai/sdk 1.2.0 → 1.3.0

package/src/internal/utils/values.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { NebulaError } 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 NebulaError(`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 NebulaError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new NebulaError(`${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 NebulaError(`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 NebulaError(`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/lib/dx.ts

@@ -0,0 +1,459 @@
+import { Nebula as GeneratedNebula, type ClientOptions } from '../client';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import type { PromiseOrValue } from '../internal/types';
+import type { RequestOptions } from '../internal/request-options';
+import type { HealthResponse } from '../resources/top-level';
+import type {
+  CollectionCreateParams,
+  CollectionCreateResponse,
+  CollectionDeleteResponse,
+  CollectionListParams,
+  CollectionListResponse,
+  CollectionRetrieveByNameResponse,
+  CollectionRetrieveResponse,
+  CollectionUpdateParams,
+  CollectionUpdateResponse,
+} from '../resources/collections';
+import type {
+  ConnectorConnectResponse,
+  ConnectorDisconnectResponse,
+  ConnectorListProvidersResponse,
+  ConnectorListResponse,
+  ConnectorRetrieveResponse,
+  ConnectorSyncResponse,
+} from '../resources/connectors';
+import type {
+  MemoryAppendParams,
+  MemoryCreateParams,
+  MemoryCreateResponse,
+  MemoryCreateUploadParams,
+  MemoryCreateUploadResponse,
+  MemoryDeleteManyResponse,
+  MemoryDeleteResponse,
+  MemoryListParams,
+  MemoryListResponse,
+  MemoryRetrieveResponse,
+  MemorySearchParams,
+  MemorySearchResponse,
+  MemoryUpdateParams,
+  MemoryUpdateResponse,
+} from '../resources/memories';
+import type {
+  SnapshotExportResponse,
+  SnapshotImportParams,
+  SnapshotImportResponse,
+} from '../resources/snapshots';
+import { path } from '../internal/utils/path';
+
+type ResultsOf<T> = T extends { results: infer R } ? R : T;
+type MemoryCreateResult = MemoryCreateResponse['results'];
+type StoredMemoryResult = string | MemoryCreateResult;
+type SnapshotMemoryInput = MemoryCreateInput & { snapshot: NonNullable<MemoryCreateParams['snapshot']> };
+type NonSnapshotMemoryInput = MemoryInput & { snapshot?: null | undefined };
+type RequestPath = `/${string}` | `http://${string}` | `https://${string}`;
+type CompatClientOptions = ClientOptions & {
+  api_key?: string | null;
+  baseUrl?: string | null;
+  base_url?: string | null;
+  bearerToken?: string | null;
+  bearer_token?: string | null;
+};
+
+export interface MemoryCommonInput {
+  collection_id?: string | null;
+  collectionId?: string | null;
+  content?: string | MemoryCreateParams['content_parts'];
+  raw_text?: string | null;
+  chunks?: Array<string> | null;
+  messages?: MemoryCreateParams['messages'];
+  metadata?: { [key: string]: unknown } | null;
+  ingestion_config?: MemoryCreateParams['ingestion_config'];
+  ingestion_mode?: MemoryCreateParams['ingestion_mode'];
+}
+
+export interface MemoryCreateInput
+  extends MemoryCommonInput,
+    Pick<
+      MemoryCreateParams,
+      'content_parts' | 'contents' | 'engram_type' | 'name' | 'snapshot' | 'speaker_id' | 'speaker_name'
+    > {
+  memory_id?: undefined | null;
+}
+
+export interface MemoryAppendInput extends Omit<MemoryCommonInput, 'ingestion_mode' | 'messages'> {
+  memory_id: string;
+  ingestion_mode?: MemoryAppendParams['ingestion_mode'];
+  messages?: MemoryAppendParams['messages'];
+}
+
+export type MemoryInput = MemoryCreateInput | MemoryAppendInput;
+
+export class Nebula extends GeneratedNebula {
+  constructor(options: CompatClientOptions = {}) {
+    super(normalizeAuthOptions(normalizeClientOptions(options)));
+  }
+
+  override health(options?: RequestOptions): APIPromise<HealthResponse> {
+    return this.get('/v1/health', {
+      ...options,
+      headers: buildHeaders([options?.headers, { 'X-API-Key': null, Authorization: null }]),
+      __security: {},
+    });
+  }
+
+  async storeMemory(memory: SnapshotMemoryInput, options?: RequestOptions): Promise<MemoryCreateResult>;
+  async storeMemory(memory: NonSnapshotMemoryInput, options?: RequestOptions): Promise<string>;
+  async storeMemory(memory: MemoryInput, options?: RequestOptions): Promise<StoredMemoryResult>;
+  async storeMemory(memory: MemoryInput, options?: RequestOptions): Promise<StoredMemoryResult> {
+    if (memory.memory_id != null) {
+      const memoryID = memory.memory_id;
+      await this.memories.append(memoryID, toMemoryAppendParams(memory), options);
+      return memoryID;
+    }
+
+    const response = await this.memories.create(toMemoryCreateParams(memory), options);
+    const result = unwrapResults(response);
+    if (isMemoryCreateResult(result)) {
+      return result;
+    }
+    return extractID(result);
+  }
+
+  storeMemories(memories: SnapshotMemoryInput[], options?: RequestOptions): Promise<MemoryCreateResult[]>;
+  storeMemories(memories: NonSnapshotMemoryInput[], options?: RequestOptions): Promise<string[]>;
+  storeMemories(memories: MemoryInput[], options?: RequestOptions): Promise<StoredMemoryResult[]>;
+  storeMemories(memories: MemoryInput[], options?: RequestOptions): Promise<StoredMemoryResult[]> {
+    return Promise.all(memories.map((memory) => this.storeMemory(memory, options)));
+  }
+
+  getMemory(id: string, options?: RequestOptions): Promise<MemoryRetrieveResponse['results']> {
+    return unwrap(this.memories.retrieve(id, options));
+  }
+
+  updateMemory(
+    id: string,
+    params: MemoryUpdateParams,
+    options?: RequestOptions,
+  ): Promise<MemoryUpdateResponse['results']> {
+    return unwrap(this.memories.update(id, params, options));
+  }
+
+  listMemories(
+    query: MemoryListParams | string | string[],
+    options?: RequestOptions,
+  ): Promise<MemoryListResponse['results']> {
+    const normalized =
+      typeof query === 'string' || Array.isArray(query) ? { collection_ids: arrayify(query) } : query;
+    return unwrap(this.memories.list(normalized, options));
+  }
+
+  search(body: MemorySearchParams, options?: RequestOptions): Promise<ResultsOf<MemorySearchResponse>> {
+    const collectionIDs =
+      Array.isArray(body.collection_ids) ? body.collection_ids
+      : body.collection_ids ? [body.collection_ids]
+      : undefined;
+    return unwrap(
+      this.memories.search(body, {
+        ...options,
+        headers: buildHeaders([options?.headers, collectionAffinityHeaders(collectionIDs)]),
+      }),
+    );
+  }
+
+  healthCheck(options?: RequestOptions): Promise<HealthResponse['results']> {
+    return unwrap(this.health(options));
+  }
+
+  createCollection(
+    body: CollectionCreateParams,
+    options?: RequestOptions,
+  ): Promise<CollectionCreateResponse['results']> {
+    return unwrap(this.collections.create(body, options));
+  }
+
+  getCollection(id: string, options?: RequestOptions): Promise<CollectionRetrieveResponse['results']> {
+    return unwrap(this.collections.retrieve(id, options));
+  }
+
+  getCollectionByName(
+    name: string,
+    options?: RequestOptions,
+  ): Promise<CollectionRetrieveByNameResponse['results']> {
+    return unwrap(this.collections.retrieveByName(name, {}, options));
+  }
+
+  listCollections(
+    query: CollectionListParams = {},
+    options?: RequestOptions,
+  ): Promise<CollectionListResponse['results']> {
+    return unwrap(this.collections.list(query, options));
+  }
+
+  updateCollection(
+    id: string,
+    body: CollectionUpdateParams,
+    options?: RequestOptions,
+  ): Promise<CollectionUpdateResponse['results']> {
+    return unwrap(this.collections.update(id, body, options));
+  }
+
+  deleteCollection(id: string, options?: RequestOptions): Promise<boolean> {
+    return this.collections.delete(id, options).then((response: CollectionDeleteResponse) => {
+      const result = unwrapResults(response) as { success?: boolean };
+      return Boolean(result.success);
+    });
+  }
+
+  createCluster = this.createCollection;
+  getCluster = this.getCollection;
+  getClusterByName = this.getCollectionByName;
+  listClusters = this.listCollections;
+  updateCluster = this.updateCollection;
+  deleteCluster = this.deleteCollection;
+
+  listProviders(options?: RequestOptions): Promise<ConnectorListProvidersResponse['results']> {
+    return unwrap(this.connectors.listProviders(options));
+  }
+
+  connectProvider(
+    provider: string,
+    collectionID: string,
+    config?: Record<string, unknown>,
+    options?: RequestOptions,
+  ): Promise<ConnectorConnectResponse['results']> {
+    return unwrap(
+      this.connectors.connect(
+        provider,
+        config === undefined ? { collection_id: collectionID } : { collection_id: collectionID, config },
+        options,
+      ),
+    );
+  }
+
+  listConnections(collectionID: string, options?: RequestOptions): Promise<ConnectorListResponse['results']> {
+    return unwrap(this.connectors.list({ collection_id: collectionID }, options));
+  }
+
+  getConnection(
+    connectionID: string,
+    options?: RequestOptions,
+  ): Promise<ConnectorRetrieveResponse['results']> {
+    return unwrap(this.connectors.retrieve(connectionID, options));
+  }
+
+  triggerSync(connectionID: string, options?: RequestOptions): Promise<ConnectorSyncResponse['results']> {
+    return unwrap(this.connectors.sync(connectionID, options));
+  }
+
+  disconnectConnection(
+    connectionID: string,
+    deleteMemories = false,
+    options?: RequestOptions,
+  ): Promise<ConnectorDisconnectResponse['results']> {
+    return unwrap(this.connectors.disconnect(connectionID, { delete_memories: deleteMemories }, options));
+  }
+
+  disconnect(
+    connectionID: string,
+    deleteMemories = false,
+    options?: RequestOptions,
+  ): Promise<ConnectorDisconnectResponse['results']> {
+    return this.disconnectConnection(connectionID, deleteMemories, options);
+  }
+
+  getUploadUrl(
+    params: MemoryCreateUploadParams,
+    options?: RequestOptions,
+  ): Promise<MemoryCreateUploadResponse['results']> {
+    return unwrap(this.memories.createUpload(params, options));
+  }
+
+  exportSnapshot(collectionID: string, options?: RequestOptions): Promise<SnapshotExportResponse['results']> {
+    return unwrap(this.snapshots.export({ collection_id: collectionID }, options));
+  }
+
+  importSnapshot(
+    snapshot: SnapshotImportParams['snapshot'],
+    options?: RequestOptions,
+  ): Promise<SnapshotImportResponse['results']> {
+    return unwrap(this.snapshots.import({ snapshot }, options));
+  }
+
+  deleteMemory(memoryID: string, options?: PromiseOrValue<RequestOptions>): APIPromise<boolean> {
+    return super
+      .delete<MemoryDeleteResponse>(path`/v1/memories/${memoryID}`, options)
+      ._thenUnwrap(() => true);
+  }
+
+  deleteMemories(
+    memoryIDs: string[],
+    options?: PromiseOrValue<RequestOptions>,
+  ): APIPromise<MemoryDeleteManyResponse> {
+    return super.post<MemoryDeleteManyResponse>(
+      '/v1/memories/delete',
+      Promise.resolve(options).then((resolved) => ({ ...resolved, body: memoryIDs })),
+    );
+  }
+
+  deletePath<Rsp>(path: string, opts?: PromiseOrValue<RequestOptions>): APIPromise<Rsp> {
+    return super.delete(path, opts);
+  }
+
+  override delete<Rsp>(path: RequestPath, opts?: PromiseOrValue<RequestOptions>): APIPromise<Rsp>;
+  override delete(memoryID: string, opts?: PromiseOrValue<RequestOptions>): APIPromise<boolean>;
+  override delete(memoryIDs: string[]): APIPromise<MemoryDeleteManyResponse>;
+  override delete<Rsp>(path: string, opts?: PromiseOrValue<RequestOptions>): APIPromise<Rsp>;
+  override delete(
+    pathOrMemoryIDs: string | string[],
+    opts?: PromiseOrValue<RequestOptions>,
+  ): APIPromise<unknown> {
+    if (Array.isArray(pathOrMemoryIDs)) {
+      return this.deleteMemories(pathOrMemoryIDs, opts);
+    }
+
+    if (isRequestPath(pathOrMemoryIDs)) {
+      return super.delete(pathOrMemoryIDs, opts);
+    }
+
+    return this.deleteMemory(pathOrMemoryIDs, opts);
+  }
+}
+
+function normalizeAuthOptions(options: ClientOptions): ClientOptions {
+  if (options.apiKey && options.accessToken == null && !looksLikeNebulaAPIKey(options.apiKey)) {
+    return { ...options, apiKey: null, accessToken: options.apiKey };
+  }
+  return options;
+}
+
+function normalizeClientOptions(options: CompatClientOptions): ClientOptions {
+  const {
+    api_key: apiKeyAlias,
+    baseUrl,
+    base_url: baseURLAlias,
+    bearerToken,
+    bearer_token: bearerTokenAlias,
+    ...rest
+  } = options;
+  return {
+    ...rest,
+    apiKey: firstDefined(rest.apiKey, apiKeyAlias),
+    accessToken: firstDefined(rest.accessToken, bearerToken, bearerTokenAlias),
+    baseURL: firstDefined(rest.baseURL, baseUrl, baseURLAlias),
+  };
+}
+
+function firstDefined<T>(...values: (T | undefined)[]): T | undefined {
+  return values.find((value) => value !== undefined);
+}
+
+function looksLikeNebulaAPIKey(token: string): boolean {
+  const [publicPart, rawPart, extra] = token.split('.');
+  return (
+    extra === undefined &&
+    publicPart !== undefined &&
+    rawPart !== undefined &&
+    rawPart.length > 0 &&
+    (publicPart.startsWith('key_') || publicPart.startsWith('neb_'))
+  );
+}
+
+function toMemoryCreateParams(memory: MemoryCreateInput): MemoryCreateParams {
+  const collectionID = memory.collection_id ?? memory.collectionId;
+  const { collectionId: _collectionId, content, memory_id: _memoryID, ...rest } = memory;
+  const params = { ...rest } as MemoryCreateParams;
+
+  if (collectionID !== undefined) {
+    params.collection_id = collectionID;
+  }
+
+  if (content != null) {
+    if (typeof content === 'string') {
+      params.raw_text = content;
+    } else {
+      params.content_parts = content;
+    }
+  }
+
+  if (params.messages && !params.engram_type) {
+    params.engram_type = 'conversation';
+  }
+
+  return params;
+}
+
+function toMemoryAppendParams(memory: MemoryAppendInput): MemoryAppendParams {
+  const collectionID = memory.collection_id ?? memory.collectionId;
+  if (!collectionID) {
+    throw new Error('collection_id is required when appending to an existing memory');
+  }
+
+  const {
+    collection_id: _collectionID,
+    collectionId: _collectionId,
+    memory_id: _memoryID,
+    content,
+    ...rest
+  } = memory;
+  const params: MemoryAppendParams = {
+    ...(rest as Omit<MemoryAppendParams, 'collection_id'>),
+    collection_id: collectionID,
+  };
+
+  if (content != null) {
+    if (typeof content === 'string') {
+      params.raw_text = content;
+    } else if (Array.isArray(content) && content.every((item) => typeof item === 'string')) {
+      params.chunks = content;
+    } else if (Array.isArray(content)) {
+      params.messages = content as unknown as NonNullable<MemoryAppendParams['messages']>;
+    }
+  }
+
+  return params;
+}
+
+function unwrap<T>(promise: PromiseLike<T>): Promise<ResultsOf<T>> {
+  return Promise.resolve(promise).then((response) => unwrapResults(response) as ResultsOf<T>);
+}
+
+function unwrapResults<T>(response: T): unknown {
+  return typeof response === 'object' && response !== null && 'results' in response ?
+      (response as { results: unknown }).results
+    : response;
+}
+
+function extractID(value: unknown): string {
+  if (typeof value === 'object' && value !== null) {
+    const record = value as Record<string, unknown>;
+    const id =
+      record['id'] ?? record['memory_id'] ?? record['engram_id'] ?? record['ephemeral_collection_id'];
+    if (typeof id === 'string') {
+      return id;
+    }
+  }
+  throw new Error('Nebula memory create response did not include an id');
+}
+
+function isMemoryCreateResult(value: unknown): value is MemoryCreateResult {
+  return typeof value === 'object' && value !== null && 'snapshot' in value;
+}
+
+function arrayify(value: string | string[]): string[] {
+  return Array.isArray(value) ? value : [value];
+}
+
+function collectionAffinityHeaders(collectionIDs?: string[]) {
+  if (!collectionIDs?.length) {
+    return undefined;
+  }
+  return {
+    'X-Nebula-Collection-Id':
+      collectionIDs.length === 1 ? collectionIDs[0] : [...collectionIDs].sort().join(','),
+  };
+}
+
+function isRequestPath(value: string): boolean {
+  return value.startsWith('/') || /^https?:\/\//i.test(value);
+}

package/src/resource.ts

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