aegis-platform-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,497 @@
+type QueryParams = Record<string, string | number | boolean | undefined | null>;
+interface RequestOptions {
+    params?: QueryParams;
+    json?: unknown;
+    signal?: AbortSignal;
+}
+/** The verb-agnostic transport contract every resource is built on. */
+interface Transport {
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+}
+
+/**
+ * Core wire types — mirrors `aegis/types.py` in the Python SDK.
+ *
+ * Many endpoints return backend-shaped JSON that the Python SDK types as
+ * `dict`; those are `Json` here. As endpoints stabilize they graduate to
+ * named interfaces (same policy as the Python SDK).
+ */
+type Json = Record<string, unknown>;
+interface TokenPair {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_in: number;
+    must_change_password: boolean;
+}
+interface Tenant {
+    id: string;
+    slug: string;
+    display_name: string;
+    features: Json;
+}
+interface DevMode {
+    enabled: boolean;
+    until?: string | null;
+}
+interface WhoAmI {
+    user_id: string;
+    username: string;
+    display_name: string;
+    email?: string | null;
+    tenant?: Tenant | null;
+    clearances: string[];
+    roles: string[];
+    permissions: string[];
+    must_change_password: boolean;
+    totp_enabled: boolean;
+    dev_mode?: DevMode | null;
+}
+interface User {
+    id: string;
+    tenant_id: string;
+    username: string;
+    display_name: string;
+    email?: string | null;
+    active: boolean;
+    clearances: string[];
+    roles: string[];
+    must_change_password: boolean;
+    totp_enabled: boolean;
+}
+interface Role {
+    id: string;
+    tenant_id?: string | null;
+    key: string;
+    name: string;
+    description: string;
+    is_system: boolean;
+    priority: number;
+    permission_keys: string[];
+    parent_role_ids: string[];
+}
+interface Permission {
+    id: string;
+    key: string;
+    resource: string;
+    action: string;
+    description: string;
+    is_system: boolean;
+}
+interface OsdkToken {
+    id: string;
+    name: string;
+    scopes: string[];
+    expires_at?: string | null;
+    last_used_at?: string | null;
+    revoked: boolean;
+    created_at?: string | null;
+}
+/** Returned once on create/rotate — `token` is the plaintext secret. */
+interface OsdkTokenWithSecret extends OsdkToken {
+    token: string;
+}
+
+interface LoginOptions {
+    totpCode?: string;
+    /** Attach the issued JWT to the client for subsequent calls (default true). */
+    attach?: boolean;
+}
+/** `client.auth.*` — login, whoami, dev-mode. */
+declare class AuthResource {
+    private readonly t;
+    private readonly setToken;
+    constructor(t: Transport, setToken: (token: string | null) => void);
+    login(username: string, password: string, opts?: LoginOptions): Promise<TokenPair>;
+    me(): Promise<WhoAmI>;
+    /** Activate a vendor dev-mode session; requires the `vendor` role. */
+    enableDevMode(password: string): Promise<DevMode>;
+}
+
+declare class UsersResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(): Promise<User[]>;
+    get(userId: string): Promise<User>;
+}
+declare class RolesResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(): Promise<Role[]>;
+    get(roleId: string): Promise<Role>;
+}
+declare class GroupsResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Json[]>;
+    get(groupId: string): Promise<Json>;
+    create(name: string, description?: string): Promise<Json>;
+    update(groupId: string, patch: {
+        name?: string;
+        description?: string;
+    }): Promise<Json>;
+    delete(groupId: string): Promise<void>;
+    listMembers(groupId: string): Promise<Json[]>;
+    addMember(groupId: string, userId: string): Promise<Json>;
+    removeMember(groupId: string, userId: string): Promise<void>;
+    listForUser(userId: string): Promise<Json[]>;
+}
+declare class PermissionsResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(resource?: string): Promise<Permission[]>;
+}
+declare class NavResource {
+    private readonly t;
+    constructor(t: Transport);
+    tree(asRoleId?: string): Promise<Json>;
+}
+/** `client.iam.*` — users, roles, groups, permissions, nav tree. */
+declare class IamResource {
+    readonly users: UsersResource;
+    readonly roles: RolesResource;
+    readonly groups: GroupsResource;
+    readonly permissions: PermissionsResource;
+    readonly nav: NavResource;
+    constructor(t: Transport);
+}
+
+/** `client.osdk.*` — OSDK application token management (Governance → OSDK). */
+declare class OsdkResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(): Promise<OsdkToken[]>;
+    get(tokenId: string): Promise<OsdkToken>;
+    /** Returns the plaintext secret ONCE — stash it like any other secret. */
+    create(name: string, scopes: string[], expiresAt?: string): Promise<OsdkTokenWithSecret>;
+    rotate(tokenId: string): Promise<OsdkTokenWithSecret>;
+    revoke(tokenId: string): Promise<void>;
+}
+
+interface OperatorTaskListOptions {
+    status?: string;
+    project_id?: string;
+    origin?: string;
+    mine?: boolean;
+    limit?: number;
+}
+interface OperatorTaskCreate {
+    prompt_text: string;
+    title?: string;
+    project_id?: string;
+    priority?: string;
+    parent_task_id?: string;
+    markings?: string[];
+}
+declare class OperatorTasksResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(opts?: OperatorTaskListOptions): Promise<Json[]>;
+    get(taskId: string): Promise<Json>;
+    create(input: OperatorTaskCreate): Promise<Json>;
+    cancel(taskId: string): Promise<Json>;
+    retry(taskId: string): Promise<Json>;
+    reprioritize(taskId: string, priority: string): Promise<Json>;
+}
+/** `client.operator.*` — operator task queue (NL kanban). */
+declare class OperatorResource {
+    readonly tasks: OperatorTasksResource;
+    constructor(t: Transport);
+}
+
+declare class ObjectsResource {
+    private readonly t;
+    constructor(t: Transport);
+    get(objectId: string): Promise<Json>;
+    list(kind: string, opts?: {
+        limit?: number;
+        offset?: number;
+        q?: string;
+    }): Promise<Json[]>;
+    create(kind: string, properties: Json, name?: string): Promise<Json>;
+    createMany(kind: string, items: Json[], markings?: string[]): Promise<Json>;
+    delete(objectId: string): Promise<Json>;
+    bulkDelete(opts: {
+        object_ids?: string[];
+        kind?: string;
+        dry_run?: boolean;
+        confirm?: boolean;
+        expected_count?: number;
+    }): Promise<Json>;
+    links(objectId: string): Promise<Json[]>;
+    history(objectId: string): Promise<Json[]>;
+    queryTimeseries(objectId: string, propertyName: string, opts?: {
+        from_time?: string;
+        to_time?: string;
+        max_points?: number;
+    }): Promise<Json>;
+    appendTimeseries(objectId: string, propertyName: string, points: Json[]): Promise<Json>;
+}
+declare class GraphResource {
+    private readonly t;
+    constructor(t: Transport);
+    expand(seedId: string, opts?: {
+        depth?: number;
+        limit?: number;
+    }): Promise<Json>;
+}
+declare class ExplorerResource {
+    private readonly t;
+    constructor(t: Transport);
+    histogram(property: string, filters?: Json): Promise<Json[]>;
+    timeline(filters?: Json, bin?: string): Promise<Json[]>;
+}
+interface ObjectTypeWrite {
+    title_property: string;
+    properties: Json;
+    display_name?: string;
+    enforce?: boolean;
+    markings?: string[];
+}
+declare class ObjectTypesResource {
+    private readonly t;
+    constructor(t: Transport);
+    get(kind: string): Promise<Json>;
+    create(kind: string, input: ObjectTypeWrite): Promise<Json>;
+    update(kind: string, input: ObjectTypeWrite): Promise<Json>;
+    delete(kind: string): Promise<Json>;
+}
+declare class LinkTypesResource {
+    private readonly t;
+    constructor(t: Transport);
+    declare(input: {
+        source_kind: string;
+        target_kind: string;
+        relation: string;
+        cardinality: string;
+        inverse_label?: string;
+    }): Promise<Json>;
+    delete(edgeId: string): Promise<Json>;
+}
+/** `client.ontology.*` — objects, graph, explorer, object/link types, OSDK manifest. */
+declare class OntologyResource {
+    private readonly t;
+    readonly objects: ObjectsResource;
+    readonly graph: GraphResource;
+    readonly explorer: ExplorerResource;
+    readonly objectTypes: ObjectTypesResource;
+    readonly linkTypes: LinkTypesResource;
+    constructor(t: Transport);
+    /** Shortcut — same as `objectTypes.get(kind)`. */
+    objectType(kind: string): Promise<Json>;
+    osdkManifest(): Promise<Json[]>;
+    osdkFunctions(): Promise<Json[]>;
+    osdkGenerate(lang?: string): Promise<Json>;
+}
+
+declare class FlowsResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(): Promise<Json[]>;
+    get(flowId: string): Promise<Json>;
+    runs(flowId: string): Promise<Json[]>;
+    patch(flowId: string, payload: Json): Promise<Json>;
+    run(flowId: string, dryRun?: boolean): Promise<Json>;
+}
+declare class AgentsResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(): Promise<Json[]>;
+    get(agentId: string): Promise<Json>;
+    patch(agentId: string, config: Json): Promise<Json>;
+    manualRun(agentId: string): Promise<Json>;
+    runs(agentId: string): Promise<Json[]>;
+}
+declare class ModelsResource {
+    private readonly t;
+    constructor(t: Transport);
+    catalog(provider?: string): Promise<Json[]>;
+    defaults(): Promise<Json[]>;
+    setDefault(input: {
+        provider: string;
+        model: string;
+        purpose?: string;
+        provider_id?: string;
+    }): Promise<Json>;
+}
+declare class BudgetResource {
+    private readonly t;
+    constructor(t: Transport);
+    get(): Promise<Json>;
+    set(tokensPerMonth: number): Promise<Json>;
+}
+/** `client.aip.*` — flows, agents, model catalog/defaults, LLM budget. */
+declare class AipResource {
+    readonly flows: FlowsResource;
+    readonly agents: AgentsResource;
+    readonly models: ModelsResource;
+    readonly budget: BudgetResource;
+    constructor(t: Transport);
+}
+
+interface FunctionCreate {
+    slug: string;
+    display_name: string;
+    source: string;
+    language?: string;
+    signature?: Json;
+    description?: string;
+    markings?: string[];
+    classification_level?: string;
+    project_id?: string;
+    strict_signature?: boolean;
+    allow_network?: boolean;
+}
+interface PullRequestCreate {
+    title: string;
+    proposed_source: string;
+    description?: string;
+    proposed_signature?: Json;
+    proposed_language?: string;
+    required_approvers?: number;
+    target_branch?: string;
+}
+/** `client.functions.*` — Code Functions (/platform/v26/functions). */
+declare class FunctionsResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(): Promise<Json[]>;
+    get(slug: string): Promise<Json>;
+    create(input: FunctionCreate): Promise<Json>;
+    invoke(slug: string, inputs?: Json, opts?: {
+        branch?: string;
+        draft?: boolean;
+    }): Promise<Json>;
+    tests(slug: string): Promise<Json[]>;
+    addTest(slug: string, name: string, inputs?: Json, expectedContains?: string): Promise<Json>;
+    runTest(slug: string, testId: string): Promise<Json>;
+    runTests(slug: string): Promise<Json>;
+    publish(slug: string, branch?: string): Promise<Json>;
+    versions(slug: string): Promise<Json[]>;
+    pullRequests(slug: string, status?: string): Promise<Json[]>;
+    openPullRequest(slug: string, input: PullRequestCreate): Promise<Json>;
+    updatePullRequest(slug: string, prId: string, patch: Json): Promise<Json>;
+    runPrCi(slug: string, prId: string): Promise<Json>;
+    reviewPullRequest(slug: string, prId: string, decision: string, comment?: string): Promise<Json>;
+    mergePullRequest(slug: string, prId: string): Promise<Json>;
+}
+/** `client.codeRepositories.*` — repos/branches around Code Functions. */
+declare class CodeRepositoriesResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(): Promise<Json[]>;
+    create(input: {
+        slug: string;
+        display_name: string;
+        description?: string;
+        default_branch?: string;
+    }): Promise<Json>;
+    branches(repoId: string): Promise<Json[]>;
+    createBranch(repoId: string, name: string, description?: string): Promise<Json>;
+    functions(repoId: string): Promise<Json[]>;
+    assignFunction(repoId: string, slug: string): Promise<Json>;
+    runCi(repoId: string): Promise<Json>;
+    mergeBranch(repoId: string, sourceBranch: string, into?: string): Promise<Json>;
+}
+
+type TransactionKind = "SNAPSHOT" | "APPEND" | "UPDATE" | "DELETE";
+/** `client.datasets.*` — datasets, branches, transactions, classification, markings. */
+declare class DatasetsResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(): Promise<Json[]>;
+    get(name: string): Promise<Json>;
+    sample(name: string, limit?: number): Promise<Json>;
+    listBranches(name: string): Promise<Json[]>;
+    createBranch(name: string, branchName: string, opts?: {
+        from_branch?: string;
+        from_asset_id?: string;
+        description?: string;
+        project_id?: string;
+    }): Promise<Json>;
+    deactivateBranch(name: string, branchName: string): Promise<Json>;
+    listTransactions(name: string, branch?: string): Promise<Json[]>;
+    beginTransaction(name: string, kind: TransactionKind, branch?: string): Promise<Json>;
+    commitTransaction(name: string, txId: string, inputPayload: Json): Promise<Json>;
+    abortTransaction(name: string, txId: string, reason?: string): Promise<Json>;
+    mergeFastForward(name: string, source: string, into: string): Promise<Json>;
+    /** 409 responses carry the conflict body in `AegisAPIError.payload`. */
+    mergeThreeWay(name: string, source: string, into: string, resolutions?: Json): Promise<Json>;
+    getClassification(name: string): Promise<Json>;
+    setClassification(name: string, patch: {
+        data_classification?: string;
+        file_classification?: string;
+    }): Promise<Json>;
+    listMarkings(name: string): Promise<Json[]>;
+    applyMarking(name: string, markingId: string): Promise<Json>;
+    removeMarking(name: string, markingId: string): Promise<void>;
+}
+
+interface AegisClientOptions {
+    /** Root URL of the AEGIS deployment, e.g. `https://aegis.example.com`.
+     *  Falls back to `process.env.AEGIS_API_URL`, then `http://localhost:8002`. */
+    baseUrl?: string;
+    /** Bearer token — a JWT (`eyJ…`) or an OSDK key (`osdk_…`).
+     *  Falls back to `process.env.AEGIS_TOKEN`. Omit for `auth.login(...)` flows. */
+    token?: string;
+    /** Per-request timeout in milliseconds. Defaults to 15000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (tests, proxies, polyfills). */
+    fetch?: typeof globalThis.fetch;
+}
+declare class AegisClient implements Transport {
+    readonly baseUrl: string;
+    private _token;
+    private readonly timeoutMs;
+    private readonly _fetch;
+    readonly auth: AuthResource;
+    readonly iam: IamResource;
+    readonly osdk: OsdkResource;
+    readonly operator: OperatorResource;
+    readonly ontology: OntologyResource;
+    readonly aip: AipResource;
+    readonly functions: FunctionsResource;
+    readonly codeRepositories: CodeRepositoriesResource;
+    readonly datasets: DatasetsResource;
+    constructor(options?: AegisClientOptions);
+    /** Replace the active bearer token (or clear with `null`). */
+    setToken(token: string | null): void;
+    get token(): string | null;
+    /** Generic escape hatch — call any AEGIS endpoint not yet wrapped. */
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+}
+
+/**
+ * Exception hierarchy for the AEGIS SDK — mirrors `aegis.exceptions` in the
+ * Python SDK. Callers can catch the broad `AegisAPIError` or react to
+ * specific subclasses:
+ *
+ * ```ts
+ * try {
+ *   await client.iam.users.list();
+ * } catch (err) {
+ *   if (err instanceof PermissionDeniedError) console.log("missing perm:", err.detail);
+ *   else if (err instanceof AegisAPIError) console.log(err.statusCode, err.detail);
+ * }
+ * ```
+ */
+declare class AegisAPIError extends Error {
+    readonly statusCode: number;
+    readonly detail: string;
+    readonly payload: unknown;
+    constructor(statusCode: number, detail?: string, payload?: unknown);
+}
+/** 401 — invalid / expired token, missing credentials, locked account. */
+declare class AuthError extends AegisAPIError {
+}
+/** 403 — authenticated but lacks the permission for this call. */
+declare class PermissionDeniedError extends AegisAPIError {
+}
+/** 404 — the addressed resource does not exist (or is hidden by tenant scope). */
+declare class NotFoundError extends AegisAPIError {
+}
+
+export { AegisAPIError, AegisClient, type AegisClientOptions, AuthError, type DevMode, type FunctionCreate, type Json, type LoginOptions, NotFoundError, type ObjectTypeWrite, type OperatorTaskCreate, type OperatorTaskListOptions, type OsdkToken, type OsdkTokenWithSecret, type Permission, PermissionDeniedError, type PullRequestCreate, type QueryParams, type RequestOptions, type Role, type Tenant, type TokenPair, type TransactionKind, type Transport, type User, type WhoAmI };