aegis-platform-sdk 1.0.0 → 1.3.0

package/dist/index.d.cts

@@ -489,6 +489,30 @@ declare class GeoResource {
         source_name?: string;
     }): Promise<T>;
     deleteZone(zoneId: string): Promise<void>;
+    /** Builder layers of the tenant, grouped by "map" (the project). */
+    layers<T = Json>(): Promise<T>;
+    /** Creates a layer (empty inline dataset + published board). The
+     *  `node_type` derives from the name and is IMMUTABLE. */
+    createLayer<T = Json>(input: {
+        nome: string;
+        mapa?: string;
+        descricao?: string;
+    }): Promise<T>;
+    layerFeatures<T = Json>(boardId: string): Promise<T>;
+    /** Saves the drawing as a versioned SNAPSHOT. `geometry` is GeoJSON
+     *  `[lng,lat]`; `geo_style` travels PER FEATURE (colour/alpha/extrusion). */
+    saveLayerFeatures<T = Json>(boardId: string, rows: Json[]): Promise<T>;
+    /** Runs the board and RECONCILES — a feature deleted in the builder leaves
+     *  the map (the engine is upsert-only). */
+    publishLayer<T = Json>(boardId: string): Promise<T>;
+    /** Renames / regroups. Never changes the `node_type`; `mapa: ""` ungroups. */
+    patchLayer<T = Json>(boardId: string, changes: {
+        nome?: string;
+        mapa?: string;
+        descricao?: string;
+    }): Promise<T>;
+    /** Deletes the whole layer: materialized nodes + dataset + board. */
+    deleteLayer<T = Json>(boardId: string): Promise<T>;
 }
 /** `client.mapTemplates.*` — reusable map specs (v22).
  *  (The Python SDK's stdout `Map` builder is sandbox-IDE-only and is not ported.) */
@@ -597,6 +621,85 @@ declare class TimeSeriesResource {
     render<T = Json>(chartId: string): Promise<T>;
 }
 
+/**
+ * Body do `POST /public/v1/guest/{token}/fix` — uma leitura de GPS do visitante.
+ * O backend avalia cerca/rota/destino (evaluate_fix) e devolve
+ * inside_fence/arrived/deviated. Sem throttle e sem geofence-gate nesta rota.
+ */
+interface GuestFix {
+    lat: number;
+    lng: number;
+    accuracy?: number;
+    /** ISO-8601; o backend usa "agora" se ausente. */
+    ts?: string;
+    /** Veredito de desvio do PRÓPRIO cliente (ex.: livetracker checando contra a
+     *  rota desenhada por ruas). O backend RELAIA à portaria (paridade legado);
+     *  ausente ⇒ o backend calcula pelo desvio da reta do token. */
+    off_route?: boolean;
+}
+/** Body do `POST /{token}/document/object-sets/query`. */
+interface GuestObjectSetQuery {
+    object_type: string;
+    filter?: Json;
+    order_by?: Json;
+    /** 1..10000, default 200 no backend. */
+    limit?: number;
+}
+/**
+ * O transporte + a base URL. `mediaUrl()` precisa da base para montar um
+ * `<img src>`; o AegisClient satisfaz isto (implementa Transport e expõe
+ * `readonly baseUrl`).
+ */
+interface PublicGuestTransport extends Transport {
+    readonly baseUrl: string;
+}
+/**
+ * `client.publicGuest.*` — o lado CONSUMIDOR do guest token público
+ * (`/public/v1/guest/{token}/*`). Sem cookie e sem Authorization: o token
+ * viaja no path; construa um client anônimo (`new AegisClient({ baseUrl })`).
+ *
+ * Erros mapeados pelo transporte: 404 (token inválido/expirado/revogado —
+ * "never leaks why"), 403 (geofence-gate/ação não permitida — invoke),
+ * 429 (throttle — invoke). Visita finalizada (chegou ao destino) → 410, que
+ * cai em `AegisAPIError` com `statusCode === 410`.
+ */
+declare class PublicGuestResource {
+    private readonly t;
+    constructor(t: PublicGuestTransport);
+    private base;
+    /** Menu/resumo do token: label, subject, status, geo, ações permitidas. */
+    menu<T = Json>(token: string): Promise<T>;
+    /** Reporta uma posição GPS; o backend avalia cerca/rota/destino. */
+    fix<T = Json>(token: string, body: GuestFix): Promise<T>;
+    /** Invoca uma ação permitida do token (ex.: abrir portão). */
+    invoke<T = Json>(token: string, actionId: string, input?: Json): Promise<T>;
+    /**
+     * Onda 2 — última posição do VISITANTE amarrado a um token de MORADOR
+     * (`geo.live_ref`). Sem push: a SPA do morador faz polling desta rota. O
+     * morador só vê ESSA visita (least-privilege). Retorna `{available, lat,
+     * lng, ts, inside_fence, arrived, deviated, distance_to_target_m,
+     * visit_status}`; `available:false` enquanto o visitante não mandou fix.
+     */
+    position<T = Json>(token: string): Promise<T>;
+    /** Documento vinculado ao token (se `geo.document_id`). */
+    document<T = Json>(token: string): Promise<T>;
+    /** Consulta um object-set embutido no documento do token. */
+    queryObjectSet<T = Json>(token: string, body: GuestObjectSetQuery): Promise<T>;
+    /** Um nó da ontologia referenciado pelo documento (mascarado por ABAC). */
+    documentNode<T = Json>(token: string, nodeId: string): Promise<T>;
+    /** Descritor da Page vinculada ao token (`geo.page_slug`). */
+    page<T = Json>(token: string, slug: string): Promise<T>;
+    /** Avalia as variáveis da Page (com overrides só de variáveis estáticas). */
+    evaluatePage<T = Json>(token: string, slug: string, overrides?: Json): Promise<T>;
+    /**
+     * URL absoluta de um objeto de mídia do documento (bytes servidos com
+     * `Cache-Control: private`). Retorna string p/ `<img src>`/`<a href>` —
+     * NÃO faz request (o transporte é JSON-cêntrico). A `key` deve começar
+     * com `notepad/{doc_id}/` (validado no backend).
+     */
+    mediaUrl(token: string, key: string): string;
+}
+
 declare class AlertFeedsResource {
     private readonly t;
     constructor(t: Transport);
@@ -683,6 +786,38 @@ declare class AlertsResource {
     constructor(t: Transport);
     escalate(alertId: string): Promise<void>;
     channels<T = Json>(): Promise<T[]>;
+    /**
+     * `PUT /alerts/channels/{ref}` — point a delivery channel at its
+     * destination.
+     *
+     * Exists so this is a GESTURE: before it, sending alerts to the team's
+     * Discord (or any webhook) meant editing the tenant's JSONB in the
+     * database. Audited as `alert_channel.configured`.
+     *
+     * `ref` is the channel name (`"discord"`) or a named ref
+     * (`"discord-plantao"`, then pass `channel: "discord"`). Fields are open
+     * because the vocabulary belongs to the CHANNEL, not the core.
+     *
+     * The response returns the config MASKED — a webhook URL is the
+     * credential, and reads never hand it back whole.
+     * Perm: `alerts.routes.manage`.
+     */
+    setChannel<T = Json>(ref: string, config: AlertChannelConfigInput): Promise<T>;
+    /** `DELETE /alerts/channels/{ref}` — audited as `alert_channel.removed`. */
+    deleteChannel(ref: string): Promise<void>;
+}
+/** What `setChannel` accepts. Open-ended on purpose: the vocabulary is the
+ *  channel's, not the core's. */
+interface AlertChannelConfigInput {
+    /** Which channel a named ref belongs to (omit when ref === channel). */
+    channel?: string;
+    /** Webhook address. This IS the credential — reads return it masked. */
+    url?: string;
+    to?: string;
+    token?: string;
+    username?: string;
+    allowlist?: string[];
+    timeout?: number;
 }
 /** `client.alarms.*` — threshold alarm rules on node properties (v26). */
 declare class AlarmsResource {
@@ -726,6 +861,43 @@ declare class EventsResource {
         all?: boolean;
     }): Promise<T>;
 }
+/**
+ * Pairing state for a skill that declares the `pairing` capability (e.g. a
+ * WhatsApp station). `qr_data_url` is a ready-to-render `data:image/png;base64`.
+ */
+interface PairingInfo {
+    state: "connected" | "awaiting_scan" | "disconnected" | "error";
+    qr_data_url: string | null;
+    code: string | null;
+    expires_at: string | null;
+    detail: string;
+    /** Additive (pool station): WHICH number is pairing — single-instance skills never set it. */
+    pairing_number?: string | null;
+}
+/**
+ * Result of an inventory gesture on a skill that declares the `inventory`
+ * capability. `detail` carries the driver's own sentence ("já existe número
+ * com este identificador") — it is the operator's diagnosis, so surface it
+ * instead of a generic failure.
+ */
+interface InventoryResult {
+    ok: boolean;
+    detail: string;
+    item?: Record<string, unknown> | null;
+}
+/** A row of the connector skill catalog (`GET /governance/agents/skills`). */
+interface SkillCatalogRow {
+    skill_key: string;
+    label: string;
+    description: string;
+    category: string;
+    source: string;
+    platforms: string[];
+    requires_secrets: string[];
+    param_schema: Json[];
+    /** Additive — declared capabilities of the skill, e.g. `["pairing"]`. */
+    capabilities?: string[];
+}
 /** `client.connectors.*` — HTTP connector agents under governance. */
 declare class ConnectorsResource {
     private readonly t;
@@ -751,9 +923,31 @@ declare class ConnectorsResource {
     }): Promise<Json>;
     test<T = Json>(agentId: string): Promise<T>;
     run<T = Json>(agentId: string): Promise<T>;
+    /**
+     * Start/renew QR pairing for a skill with the `pairing` capability (WhatsApp
+     * station). Pass `{ refresh: true }` to force a fresh code.
+     */
+    pairingStart<T = PairingInfo>(agentId: string, skillKey: string, opts?: {
+        refresh?: boolean;
+        target?: string;
+    }): Promise<T>;
+    /** Read-only poll of the pairing state (no side effects). `target` aims a pool number. */
+    pairingPoll<T = PairingInfo>(agentId: string, skillKey: string, opts?: {
+        target?: string;
+    }): Promise<T>;
+    /**
+     * Add / correct / remove a sub-unit administered by a connector that
+     * declares the `inventory` capability — e.g. one number of a WhatsApp
+     * number-station.
+     *
+     * Reading is NOT here: the inventory already reaches callers through the
+     * snapshot the tick publishes on the device mirror (`GET /api/v1/edge/nodes`
+     * → `nodes[].pool`). A second read path would drift between ticks.
+     */
+    applyInventory<T = InventoryResult>(agentId: string, skillKey: string, op: "add" | "update" | "remove", item: Record<string, unknown>): Promise<T>;
     schedulerTick<T = Json>(): Promise<T>;
-    /** source ∈ native|clawhub */
-    skillCatalog<T = Json>(source?: string): Promise<T[]>;
+    /** source ∈ native|clawhub. Rows carry an additive `capabilities` field. */
+    skillCatalog<T = SkillCatalogRow>(source?: string): Promise<T[]>;
     installOpenclaw<T = Json>(slug: string): Promise<T>;
     refreshOpenclaw<T = Json>(): Promise<T>;
 }
@@ -982,6 +1176,12 @@ interface GuestTokenIssue {
     min_interval_seconds?: number;
     /** `{ fence, target, arrival_radius_m }` */
     geo?: Json;
+    /**
+     * Free-form denormalized contact (e.g. `{ phone, document, notes }`),
+     * surfaced by real-time gate screens without extra reads. Multi-domain: the
+     * site decides what goes here.
+     */
+    contact?: Json;
     /** `{ channel, to, text? }` */
     share?: Json;
     link_base?: string;
@@ -1341,14 +1541,113 @@ declare class CctvResource {
         to_ms?: number;
     }): Promise<string>;
 }
+/**
+ * A number of a pool station's inventory (`GET /api/v1/edge/nodes` →
+ * `nodes[].pool.numbers[]`). Published by the `connector.whatsapp_pool` tick.
+ */
+interface EdgePoolNumber {
+    id: string;
+    msisdn?: string;
+    role?: string;
+    owner?: string;
+    state?: string;
+    sendable?: boolean;
+    needs_gesture?: boolean;
+    banned_until?: string | null;
+    sent?: number;
+    /** Present only when a device is declared for this number (opt-in). */
+    automation?: EdgePoolAutomation | null;
+}
+/**
+ * Android relink automation for one number. The phone is an edge: when a
+ * session dies, a runner types the 8-character pairing code on the declared
+ * device. Absent when no device is declared — the number stays on the manual
+ * gesture and the row is unchanged.
+ */
+interface EdgePoolAutomation {
+    /** `"idle"` | `"pending"` | `"attempting"` | `"confirming"` | `"needs_human"` */
+    state?: string;
+    attempts?: number;
+    max_attempts?: number;
+    /** Why the automation gave up. Truncated to 160 chars by the backend. */
+    last_error?: string;
+    last_attempt_at?: string;
+    last_success_at?: string;
+    device?: {
+        serial?: string;
+        /** 0 = not reported. */
+        battery?: number;
+        screen_on?: boolean;
+        wa_foreground?: boolean;
+        at?: string;
+    };
+}
+/** Pool snapshot of a number-station device (additive `pool` on {@link EdgeNode}). */
+interface EdgePoolSummary {
+    station?: string | null;
+    state?: string | null;
+    health?: {
+        total?: number;
+        sendable?: number;
+        standby?: number;
+        needs_gesture?: number;
+        temp_banned?: number;
+        connected?: boolean;
+    };
+    numbers?: EdgePoolNumber[];
+}
+/**
+ * An edge device row from `GET /api/v1/edge/nodes`. `kind` is additive —
+ * `"camera_gateway"` | `"whatsapp_station"` | `"whatsapp_pool"` |
+ * `"autosync_bridge"` (absent = legacy camera gateway). `pool` is additive —
+ * present only on number-station devices whose connector published inventory.
+ */
+interface EdgeNode {
+    edge_id: string;
+    name: string;
+    kind?: string;
+    status: string;
+    version: string;
+    last_seen_at: string | null;
+    update_available: boolean;
+    cameras_ok: number | null;
+    pool?: EdgePoolSummary | null;
+    /**
+     * Connector behind a station-like device. `capabilities` are the ones the
+     * skill DECLARES (`"pairing"`, `"inventory"`, …) — gate each gesture by
+     * them, never by a hardcoded skill key.
+     */
+    pairing?: {
+        agent_id: string;
+        slug: string;
+        skill_key: string;
+        capabilities?: string[];
+    } | null;
+}
 /** `client.edge.*` — edge node pairing + fleet version pinning. */
 declare class EdgeResource {
     private readonly t;
     constructor(t: Transport);
+    /**
+     * Issue a single-use pairing code (short TTL). The plaintext `code` appears
+     * ONLY in this response (hash at rest).
+     *
+     * `grants` GRANTS gestures to whichever device redeems the code (allowlist;
+     * today `["retry"]`, so a desk app can ask the station to reconnect a
+     * number). Empty — the default — is **read only**: least privilege, and
+     * granting has to be a choice. The grant travels from the code to the node
+     * and dies with it on `revoke`.
+     *
+     * Even when granted, the device never receives the gesture's ADDRESS
+     * (`agent_id`/`skill_key`): it sends the verb and the server routes it.
+     * Perm: `connectors.manage`.
+     */
     createPairingCode<T = Json>(opts?: {
         label?: string;
         ttl_seconds?: number;
+        grants?: string[];
     }): Promise<T>;
+    /** Nodes carry an additive `kind` field — see {@link EdgeNode}. */
     listNodes<T = Json>(): Promise<T>;
     listDiscovered<T = Json>(): Promise<T[]>;
     revoke<T = Json>(edgeId: string): Promise<T>;
@@ -2189,6 +2488,8 @@ declare class AegisClient implements Transport {
     readonly pages: PagesResource;
     readonly dossier: DossierResource;
     readonly timeseries: TimeSeriesResource;
+    /** Public guest-token consumer surface (`/public/v1/guest/{token}/*`). */
+    readonly publicGuest: PublicGuestResource;
     readonly alerts: AlertsResource;
     readonly alarms: AlarmsResource;
     readonly events: EventsResource;
@@ -2369,4 +2670,4 @@ interface OSDKClient {
 }
 declare function asOsdkClient(client: AegisClient): OSDKClient;
 
-export { ALL_PERMISSIONS, APPLICATIONS, AccessAuditResource, AegisAPIError, AegisClient, type AegisClientOptions, AipResource, AlarmsResource, AlertsResource, AppShellResource, AtlasResource, AuthError, AuthResource, BriefingResource, CAPABILITY_PERMISSIONS, CLASSIFICATION_LABEL, CLASSIFICATION_RANK, CampaignResource, type CapabilityPermissionKey, CctvResource, ChatResource, ClassificationInvariantViolation, type ClassificationLevel, CodeRepositoriesResource, CodegenResource, ComputeControlResource, ComputeResource, ComunicadosResource, ConnectorsResource, CorrelationResource, DatasetsResource, type DevMode, DocsResource, DossierResource, EdgeResource, ErasureResource, type ErasureSelector, EventsResource, FormsResource, type FunctionCreate, FunctionsResource, GeoResource, GroupsResource, type GuestTokenIssue, GuestTokensResource, type IamPermissionDef, IamResource, InferenceResource, type Json, LineageResource, type LoginOptions, MapTemplatesResource, MarketplaceResource, MarkingsResource, MediaResource, MergeResource, type MergeTarget, NAV_PERMISSIONS, type NavPermissionKey, NotFoundError, NotepadResource, type OSDKClient, type ObjectTypeWrite, OntologyResource, OperatorResource, type OperatorTaskCreate, type OperatorTaskListOptions, OrganizationsResource, type OsdkApplication, OsdkResource, type OsdkToken, type OsdkTokenWithSecret, PagesResource, type Permission, PermissionDeniedError, type PermissionKey, PipelinesResource, PlatformV22Resource, PlatformV23Resource, PlatformV24Resource, PlatformV25Resource, PlatformV26Resource, ProjectsResource, PropertyMarkingsResource, type PullRequestCreate, type QueryParams, type RequestOptions, ResourceMarkingsResource, RetentionResource, type RetryOptions, type Role, RowPoliciesResource, SituationalResource, SolutionsResource, SpacesResource, type SseEvent, type Tenant, TimeSeriesResource, type TokenPair, type TransactionKind, type Transport, type User, VALID_LEVELS, VALID_PROJECT_ROLES, VideoResource, type WhoAmI, WorkshopResource, WorkspaceUpdatesResource, WorkspacesResource, applicationBySlug, applicationHas, asOsdkClient, isSystemPermission, listApplications, listPermissions, maxLevel, parseSseStream, validateApplication, validateInvariant };
+export { ALL_PERMISSIONS, APPLICATIONS, AccessAuditResource, AegisAPIError, AegisClient, type AegisClientOptions, AipResource, AlarmsResource, type AlertChannelConfigInput, AlertsResource, AppShellResource, AtlasResource, AuthError, AuthResource, BriefingResource, CAPABILITY_PERMISSIONS, CLASSIFICATION_LABEL, CLASSIFICATION_RANK, CampaignResource, type CapabilityPermissionKey, CctvResource, ChatResource, ClassificationInvariantViolation, type ClassificationLevel, CodeRepositoriesResource, CodegenResource, ComputeControlResource, ComputeResource, ComunicadosResource, ConnectorsResource, CorrelationResource, DatasetsResource, type DevMode, DocsResource, DossierResource, type EdgeNode, type EdgePoolAutomation, type EdgePoolNumber, type EdgePoolSummary, EdgeResource, ErasureResource, type ErasureSelector, EventsResource, FormsResource, type FunctionCreate, FunctionsResource, GeoResource, GroupsResource, type GuestFix, type GuestObjectSetQuery, type GuestTokenIssue, GuestTokensResource, type IamPermissionDef, IamResource, InferenceResource, type InventoryResult, type Json, LineageResource, type LoginOptions, MapTemplatesResource, MarketplaceResource, MarkingsResource, MediaResource, MergeResource, type MergeTarget, NAV_PERMISSIONS, type NavPermissionKey, NotFoundError, NotepadResource, type OSDKClient, type ObjectTypeWrite, OntologyResource, OperatorResource, type OperatorTaskCreate, type OperatorTaskListOptions, OrganizationsResource, type OsdkApplication, OsdkResource, type OsdkToken, type OsdkTokenWithSecret, PagesResource, type PairingInfo, type Permission, PermissionDeniedError, type PermissionKey, PipelinesResource, PlatformV22Resource, PlatformV23Resource, PlatformV24Resource, PlatformV25Resource, PlatformV26Resource, ProjectsResource, PropertyMarkingsResource, PublicGuestResource, type PublicGuestTransport, type PullRequestCreate, type QueryParams, type RequestOptions, ResourceMarkingsResource, RetentionResource, type RetryOptions, type Role, RowPoliciesResource, SituationalResource, type SkillCatalogRow, SolutionsResource, SpacesResource, type SseEvent, type Tenant, TimeSeriesResource, type TokenPair, type TransactionKind, type Transport, type User, VALID_LEVELS, VALID_PROJECT_ROLES, VideoResource, type WhoAmI, WorkshopResource, WorkspaceUpdatesResource, WorkspacesResource, applicationBySlug, applicationHas, asOsdkClient, isSystemPermission, listApplications, listPermissions, maxLevel, parseSseStream, validateApplication, validateInvariant };