agentstack-sdk 0.5.1-rc2 → 0.5.2-rc2

package/src/client/api/contexts/schemas.ts

@@ -0,0 +1,156 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import { artifactSchema, messageSchema } from '../../a2a/protocol/schemas';
+import { paginatedResponseSchema, paginationQuerySchema } from '../core/schemas';
+import { ContextHistoryKind } from './types';
+
+export const contextSchema = z.object({
+  id: z.string(),
+  created_at: z.string(),
+  updated_at: z.string(),
+  last_active_at: z.string(),
+  created_by: z.string(),
+  provider_id: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+});
+
+export const listContextsRequestSchema = z.object({
+  query: paginationQuerySchema
+    .extend({
+      provider_id: z.string().nullish(),
+      include_empty: z.boolean().optional(),
+    })
+    .optional(),
+});
+
+export const listContextsResponseSchema = paginatedResponseSchema.extend({
+  items: z.array(contextSchema),
+});
+
+export const createContextRequestSchema = z.object({
+  provider_id: z.string().nullish(),
+  metadata: z.record(z.string(), z.string()).nullish(),
+});
+
+export const createContextResponseSchema = contextSchema;
+
+export const readContextRequestSchema = z.object({
+  context_id: z.string(),
+});
+
+export const readContextResponseSchema = contextSchema;
+
+export const updateContextRequestSchema = z.object({
+  context_id: z.string(),
+  metadata: z.record(z.string(), z.string()).nullish(),
+});
+
+export const updateContextResponseSchema = contextSchema;
+
+export const deleteContextRequestSchema = z.object({
+  context_id: z.string(),
+});
+
+export const deleteContextResponseSchema = z.null();
+
+export const contextHistoryKind = z.enum(ContextHistoryKind);
+
+export const contextHistorySchema = z.object({
+  id: z.string(),
+  context_id: z.string(),
+  created_at: z.string(),
+  kind: contextHistoryKind,
+  data: z.union([artifactSchema, messageSchema]),
+});
+
+export const listContextHistoryRequestSchema = z.object({
+  context_id: z.string(),
+  query: paginationQuerySchema.optional(),
+});
+
+export const listContextHistoryResponseSchema = paginatedResponseSchema.extend({
+  items: z.array(contextHistorySchema),
+});
+
+export const createContextHistoryRequestSchema = z.object({
+  context_id: z.string(),
+  data: z.union([artifactSchema, messageSchema]),
+});
+
+export const createContextHistoryResponseSchema = z.null();
+
+export const patchContextMetadataRequestSchema = z.object({
+  context_id: z.string(),
+  metadata: z.record(z.string(), z.union([z.string(), z.null()])),
+});
+
+export const patchContextMetadataResponseSchema = contextSchema;
+
+export const contextTokenSchema = z.object({
+  token: z.string(),
+  expires_at: z.string().nullable(),
+});
+
+export const resourceIdPermissionSchema = z.object({
+  id: z.string(),
+});
+
+export const contextPermissionsGrantSchema = z.object({
+  files: z.array(z.literal(['read', 'write', 'extract', '*'])).optional(),
+  vector_stores: z.array(z.literal(['read', 'write', '*'])).optional(),
+  context_data: z.array(z.literal(['read', 'write', '*'])).optional(),
+});
+
+export const globalPermissionsGrantSchema = contextPermissionsGrantSchema
+  .extend({
+    feedback: z.array(z.literal('write')).optional(),
+
+    llm: z.array(z.union([z.literal('*'), resourceIdPermissionSchema])).optional(),
+    embeddings: z.array(z.union([z.literal('*'), resourceIdPermissionSchema])).optional(),
+    model_providers: z.array(z.literal(['read', 'write', '*'])).optional(),
+
+    a2a_proxy: z.array(z.union([z.literal('*'), z.string()])).optional(),
+
+    providers: z.array(z.literal(['read', 'write', '*'])).optional(),
+    provider_variables: z.array(z.literal(['read', 'write', '*'])).optional(),
+
+    contexts: z.array(z.literal(['read', 'write', '*'])).optional(),
+
+    connectors: z.array(z.literal(['read', 'write', 'proxy', '*'])).optional(),
+  })
+  .superRefine((val, ctx) => {
+    if (!val.a2a_proxy) return;
+
+    if (val.a2a_proxy.length === 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'a2a_proxy cannot be empty array',
+        path: ['a2a_proxy'],
+      });
+      return;
+    }
+
+    const hasWildcard = val.a2a_proxy.includes('*');
+    const hasOthers = val.a2a_proxy.some((v) => v !== '*');
+
+    if (hasWildcard && hasOthers) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "a2a_proxy cannot mix '*' with specific providers",
+        path: ['a2a_proxy'],
+      });
+    }
+  });
+
+export const createContextTokenRequestSchema = z.object({
+  context_id: z.string(),
+  grant_context_permissions: contextPermissionsGrantSchema.optional(),
+  grant_global_permissions: globalPermissionsGrantSchema.optional(),
+});
+
+export const createContextTokenResponseSchema = contextTokenSchema;

package/src/client/api/contexts/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type z from 'zod';
+
+import type {
+  contextHistorySchema,
+  contextPermissionsGrantSchema,
+  contextSchema,
+  contextTokenSchema,
+  createContextHistoryRequestSchema,
+  createContextHistoryResponseSchema,
+  createContextRequestSchema,
+  createContextResponseSchema,
+  createContextTokenRequestSchema,
+  createContextTokenResponseSchema,
+  deleteContextRequestSchema,
+  deleteContextResponseSchema,
+  globalPermissionsGrantSchema,
+  listContextHistoryRequestSchema,
+  listContextHistoryResponseSchema,
+  listContextsRequestSchema,
+  listContextsResponseSchema,
+  patchContextMetadataRequestSchema,
+  patchContextMetadataResponseSchema,
+  readContextRequestSchema,
+  readContextResponseSchema,
+  resourceIdPermissionSchema,
+  updateContextRequestSchema,
+  updateContextResponseSchema,
+} from './schemas';
+
+export type Context = z.infer<typeof contextSchema>;
+
+export type ListContextsRequest = z.infer<typeof listContextsRequestSchema>;
+export type ListContextsResponse = z.infer<typeof listContextsResponseSchema>;
+
+export type CreateContextRequest = z.infer<typeof createContextRequestSchema>;
+export type CreateContextResponse = z.infer<typeof createContextResponseSchema>;
+
+export type ReadContextRequest = z.infer<typeof readContextRequestSchema>;
+export type ReadContextResponse = z.infer<typeof readContextResponseSchema>;
+
+export type UpdateContextRequest = z.infer<typeof updateContextRequestSchema>;
+export type UpdateContextResponse = z.infer<typeof updateContextResponseSchema>;
+
+export type DeleteContextRequest = z.infer<typeof deleteContextRequestSchema>;
+export type DeleteContextResponse = z.infer<typeof deleteContextResponseSchema>;
+
+export enum ContextHistoryKind {
+  Artifact = 'artifact',
+  Message = 'message',
+}
+export type ContextHistory = z.infer<typeof contextHistorySchema>;
+
+export type ListContextHistoryRequest = z.infer<typeof listContextHistoryRequestSchema>;
+export type ListContextHistoryResponse = z.infer<typeof listContextHistoryResponseSchema>;
+
+export type CreateContextHistoryRequest = z.infer<typeof createContextHistoryRequestSchema>;
+export type CreateContextHistoryResponse = z.infer<typeof createContextHistoryResponseSchema>;
+
+export type PatchContextMetadataRequest = z.infer<typeof patchContextMetadataRequestSchema>;
+export type PatchContextMetadataResponse = z.infer<typeof patchContextMetadataResponseSchema>;
+
+export type ContextToken = z.infer<typeof contextTokenSchema>;
+
+export type ResourceIdPermission = z.infer<typeof resourceIdPermissionSchema>;
+export type ContextPermissionsGrant = z.infer<typeof contextPermissionsGrantSchema>;
+export type GlobalPermissionsGrant = z.infer<typeof globalPermissionsGrantSchema>;
+
+export type CreateContextTokenRequest = z.infer<typeof createContextTokenRequestSchema>;
+export type CreateContextTokenResponse = z.infer<typeof createContextTokenResponseSchema>;

package/src/client/api/core/client.ts

@@ -0,0 +1,155 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type z from 'zod';
+
+import { createConfigurationApi } from '../configuration/api';
+import { createConnectorsApi } from '../connectors/api';
+import { createContextsApi } from '../contexts/api';
+import { createFilesApi } from '../files/api';
+import { createModelProvidersApi } from '../model-providers/api';
+import { createProviderBuildsApi } from '../provider-builds/api';
+import { createProvidersApi } from '../providers/api';
+import { createUserFeedbackApi } from '../user-feedback/api';
+import { createUsersApi } from '../users/api';
+import { createVariablesApi } from '../variables/api';
+import type { HttpError, NetworkError, ParseError, ValidationError } from './errors';
+import { ApiErrorException, ApiErrorType } from './errors';
+import type { ApiFailure, ApiRequest, ApiResult, CallApi } from './types';
+import { buildRequestInit, buildRequestUrl, parseBodyText, safeReadText } from './utils';
+
+function createCallApi({ baseUrl, fetch: fetchFn }: { baseUrl: string; fetch: typeof globalThis.fetch }): CallApi {
+  return async function callApi({ method, path, schema, query, body, parseAsStream }) {
+    const requestUrl = buildRequestUrl({ baseUrl, path, query });
+    const requestInit = buildRequestInit({ method, body });
+
+    const request: ApiRequest = {
+      method,
+      url: requestUrl,
+    };
+
+    try {
+      const rawResponse = await fetchFn(requestUrl, requestInit);
+      const bodyText = parseAsStream ? rawResponse.body : await safeReadText(rawResponse);
+
+      const { ok, status, statusText, headers } = rawResponse;
+      const response = { status, statusText, bodyText };
+
+      if (!ok) {
+        return {
+          ok: false,
+          error: {
+            type: ApiErrorType.Http,
+            message: 'API Http Error',
+            request,
+            response,
+          } satisfies HttpError,
+        } satisfies ApiFailure;
+      }
+
+      const { data: parsedBody, error: parseError } = parseBodyText(bodyText, headers);
+
+      if (parseError) {
+        return {
+          ok: false,
+          error: {
+            type: ApiErrorType.Parse,
+            message: 'API Parse Error',
+            request,
+            response,
+            details: parseError,
+          } satisfies ParseError,
+        } satisfies ApiFailure;
+      }
+
+      const { data: result, success, error } = schema.safeParse(parsedBody);
+
+      if (!success) {
+        return {
+          ok: false,
+          error: {
+            type: ApiErrorType.Validation,
+            message: 'API Validation Error',
+            request,
+            response,
+            details: error,
+          } satisfies ValidationError,
+        } satisfies ApiFailure;
+      }
+
+      return {
+        ok: true,
+        data: result,
+        response,
+      };
+    } catch (details) {
+      return {
+        ok: false,
+        error: {
+          type: ApiErrorType.Network,
+          message: 'API Network Error',
+          request,
+          details,
+        } satisfies NetworkError,
+      } satisfies ApiFailure;
+    }
+  };
+}
+
+export const buildApiClient = (
+  {
+    baseUrl,
+    fetch: fetchFn,
+  }: {
+    baseUrl: string;
+    fetch?: typeof globalThis.fetch;
+  } = { baseUrl: '' },
+) => {
+  const maybeFetch = fetchFn ?? (typeof globalThis.fetch !== 'undefined' ? globalThis.fetch : undefined);
+
+  if (!maybeFetch) {
+    throw new Error(
+      'fetch is not available. In Node.js < 18 or environments without global fetch, provide a fetch implementation via the fetch option.',
+    );
+  }
+
+  const callApi = createCallApi({ baseUrl, fetch: maybeFetch });
+
+  const configurationApi = createConfigurationApi(callApi);
+  const connectorsApi = createConnectorsApi(callApi);
+  const contextsApi = createContextsApi(callApi);
+  const filesApi = createFilesApi(callApi);
+  const modelProvidersApi = createModelProvidersApi(callApi);
+  const providerBuildsApi = createProviderBuildsApi(callApi);
+  const providersApi = createProvidersApi(callApi);
+  const userFeedbackApi = createUserFeedbackApi(callApi);
+  const usersApi = createUsersApi(callApi);
+  const variablesApi = createVariablesApi(callApi);
+
+  return {
+    ...configurationApi,
+    ...connectorsApi,
+    ...contextsApi,
+    ...filesApi,
+    ...modelProvidersApi,
+    ...providerBuildsApi,
+    ...providersApi,
+    ...userFeedbackApi,
+    ...usersApi,
+    ...variablesApi,
+  };
+};
+
+export function unwrapResult<T>(result: ApiResult<T>): T;
+export function unwrapResult<T, Out extends T>(result: ApiResult<T>, schema: z.ZodType<Out>): Out;
+export function unwrapResult<T, Out extends T>(result: ApiResult<T>, schema?: z.ZodType<Out>): T | Out {
+  if (result.ok) {
+    const { data } = result;
+
+    return schema ? schema.parse(data) : data;
+  }
+
+  throw new ApiErrorException(result.error);
+}

package/src/client/api/core/errors/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './types';
+export * from './utils';

package/src/client/api/core/errors/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ZodError } from 'zod';
+
+import type { ApiRequest, ApiResponse } from '../types';
+
+export enum ApiErrorType {
+  Http = 'http',
+  Network = 'network',
+  Parse = 'parse',
+  Unknown = 'unknown',
+  Validation = 'validation',
+}
+
+export interface ApiErrorBase {
+  message: string;
+  request: ApiRequest;
+}
+
+export interface HttpError extends ApiErrorBase {
+  type: ApiErrorType.Http;
+  response: ApiResponse;
+}
+
+export interface NetworkError extends ApiErrorBase {
+  type: ApiErrorType.Network;
+  details: unknown;
+}
+
+export interface ParseError extends ApiErrorBase {
+  type: ApiErrorType.Parse;
+  response: ApiResponse;
+  details: Error;
+}
+
+export interface ValidationError extends ApiErrorBase {
+  type: ApiErrorType.Validation;
+  response: ApiResponse;
+  details: ZodError;
+}
+
+export type ApiError = HttpError | NetworkError | ParseError | ValidationError;

package/src/client/api/core/errors/utils.ts

@@ -0,0 +1,63 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { HttpError, NetworkError, ParseError, ValidationError } from './types';
+import { type ApiError, ApiErrorType } from './types';
+
+export class ApiErrorException extends Error {
+  apiError: ApiError;
+
+  constructor(apiError: ApiError) {
+    super(apiError.message);
+
+    this.apiError = apiError;
+  }
+}
+
+export function isApiError(error: unknown): error is ApiErrorException {
+  return error instanceof ApiErrorException;
+}
+
+export function isHttpError(error: unknown, status?: number): error is ApiErrorException & { apiError: HttpError } {
+  if (!isApiError(error)) {
+    return false;
+  }
+
+  const { apiError } = error;
+
+  if (apiError.type !== ApiErrorType.Http) {
+    return false;
+  }
+
+  if (typeof status === 'number') {
+    return apiError.response.status === status;
+  }
+
+  return true;
+}
+
+export function isNetworkError(error: unknown): error is ApiErrorException & { apiError: NetworkError } {
+  if (!isApiError(error)) {
+    return false;
+  }
+
+  return error.apiError.type === ApiErrorType.Network;
+}
+
+export function isParseError(error: unknown): error is ApiErrorException & { apiError: ParseError } {
+  if (!isApiError(error)) {
+    return false;
+  }
+
+  return error.apiError.type === ApiErrorType.Parse;
+}
+
+export function isValidationError(error: unknown): error is ApiErrorException & { apiError: ValidationError } {
+  if (!isApiError(error)) {
+    return false;
+  }
+
+  return error.apiError.type === ApiErrorType.Validation;
+}

package/src/client/api/core/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './client';
+export * from './errors';
+export * from './types';

package/src/client/api/core/schemas.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+export const paginationQuerySchema = z.object({
+  limit: z.number().optional(),
+  order: z.string().optional(),
+  order_by: z.string().optional(),
+  page_token: z.string().nullish(),
+});
+
+export const paginatedResponseSchema = z.object({
+  items: z.array(z.unknown()),
+  total_count: z.number(),
+  has_more: z.boolean(),
+  next_page_token: z.string().nullable(),
+});

package/src/client/api/core/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type z from 'zod';
+
+import type { buildApiClient } from './client';
+import type { ApiError } from './errors';
+
+export enum ApiMethod {
+  Get = 'GET',
+  Post = 'POST',
+  Put = 'PUT',
+  Delete = 'DELETE',
+  Patch = 'PATCH',
+}
+
+export type ApiQueryParams = Record<string, unknown>;
+export type ApiRequestBody = Record<string, unknown> | FormData;
+
+export interface ApiParams<T> {
+  method: ApiMethod;
+  path: string;
+  schema: z.ZodSchema<T>;
+  query?: ApiQueryParams;
+  body?: ApiRequestBody;
+  parseAsStream?: boolean;
+}
+
+export interface ApiRequest {
+  method: ApiMethod;
+  url: string;
+}
+
+export interface ApiResponse {
+  status: number;
+  statusText: string;
+  bodyText: ReadableStream<Uint8Array> | string | null;
+}
+
+export interface ApiSuccess<T> {
+  ok: true;
+  data: T;
+  response: ApiResponse;
+}
+
+export interface ApiFailure {
+  ok: false;
+  error: ApiError;
+}
+
+export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
+
+export type CallApi = <T>(params: ApiParams<T>) => Promise<ApiResult<T>>;
+
+export type AgentStackClient = ReturnType<typeof buildApiClient>;

package/src/client/api/core/utils.ts

@@ -0,0 +1,100 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ApiMethod, ApiQueryParams, ApiRequestBody } from './types';
+
+export function buildRequestUrl({ baseUrl, path, query }: { baseUrl: string; path: string; query?: ApiQueryParams }) {
+  const url = `${baseUrl.replace(/\/+$/, '')}${path}`;
+
+  if (query) {
+    const searchParams = new URLSearchParams();
+
+    Object.entries(query).forEach(([key, value]) => {
+      if (value != null) {
+        searchParams.append(key, String(value));
+      }
+    });
+
+    const queryString = searchParams.toString();
+
+    if (queryString) {
+      return `${url}?${queryString}`;
+    }
+  }
+
+  return url;
+}
+
+export function buildRequestInit({ method, body }: { method: ApiMethod; body?: ApiRequestBody }) {
+  const headers = new Headers();
+
+  let requestBody: FormData | string | undefined;
+
+  if (body) {
+    if (body instanceof FormData) {
+      requestBody = body;
+    } else {
+      headers.set('Content-Type', 'application/json');
+
+      requestBody = JSON.stringify(body);
+    }
+  }
+
+  return {
+    method,
+    headers,
+    body: requestBody,
+  };
+}
+
+export async function safeReadText(response: Response) {
+  try {
+    return await response.text();
+  } catch {
+    return null;
+  }
+}
+
+export function parseBodyText(
+  bodyText: ReadableStream<Uint8Array> | string | null,
+  headers: Headers,
+): {
+  data: unknown;
+  error?: Error;
+} {
+  const isStreamResponse = bodyText instanceof ReadableStream;
+
+  if (isStreamResponse) {
+    return {
+      data: bodyText,
+    };
+  }
+
+  if (bodyText == null || bodyText.trim() === '') {
+    return {
+      data: null,
+    };
+  }
+
+  const contentType = headers.get('content-type') ?? '';
+  const isJsonResponse = contentType.includes('application/json');
+
+  if (isJsonResponse) {
+    try {
+      return {
+        data: JSON.parse(bodyText),
+      };
+    } catch (error) {
+      return {
+        data: null,
+        error: error instanceof Error ? error : new Error('Failed to parse body text.'),
+      };
+    }
+  }
+
+  return {
+    data: bodyText,
+  };
+}