@secondlayer/sentinel 0.4.0 → 0.5.0

package/dist/sentinel-client.d.ts

@@ -32,14 +32,20 @@ export type Claim = {
         } | null;
     };
 };
+/** A run's status. `queued`: waiting for a slot (the worker runs a bounded number of plans at once). */
+export type RunStatus = "queued" | "running" | "done" | "error";
 export type RunSummary = {
     id: string;
     kind: string;
-    status: string;
+    status: RunStatus;
     startedAt: string;
     finishedAt: string | null;
     events: RunEvent[];
 };
+/** Not finished yet: running, or queued to run. */
+export declare const runInProgress: (status: string) => boolean;
+/** Where an unfinished run is: `queued`, else its latest progress event (`starting` before the first). */
+export declare function runPhase(run: RunSummary): string;
 export type Finding = {
     title: string;
     headline?: string;
@@ -73,7 +79,7 @@ export type PlanView = {
     access?: "verified" | "claimed";
     id: string;
     contractId: string;
-    status: string;
+    status: RunStatus;
     report?: {
         findings?: Finding[];
         plan?: {
@@ -366,6 +372,263 @@ export type StartedRun = {
     planId: string;
     existing?: boolean;
 };
+/** One contract of a repo import preview: where it sits in the repo, what it calls, whether it is worth
+ *  monitoring (`suggested`, with `why` not), and where it stands for you. */
+export type ImportContract = {
+    name: string;
+    path: string;
+    /** The plan key of exactly these bytes: `github:<owner>/<repo>@<sha>:<path>`. */
+    key: string;
+    clarityVersion: number;
+    /** Contracts of the repo it calls: they deploy before it. */
+    deps: string[];
+    /** Contracts it calls by full principal outside the repo. */
+    external: string[];
+    suggested: boolean;
+    why?: "test" | "mock" | "deployed" | "trait-only";
+    /** `in-project`: already in one of your projects. `planned`: a recent plan is reused, free. `new`: a paid plan. */
+    state: "in-project" | "planned" | "new";
+    planId?: string;
+    projectId?: string;
+};
+/** `POST /projects/import/preview`: a public Clarinet repo's contracts at a pinned commit. Writes and charges
+ *  nothing; import with its `commit`. */
+export type ImportPreview = {
+    kind: "repo";
+    owner: string;
+    repo: string;
+    ref: string;
+    commit: string;
+    /** The folder of the Clarinet project (`""` = the repo root). */
+    root: string;
+    manifests: string[];
+    requirements: string[];
+    /** The contracts call each other in a loop: listed in manifest order instead of deploy order. */
+    cycle: boolean;
+    /** In deploy order. */
+    contracts: ImportContract[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+    /** Files whose code is live on mainnet, one entry per deployer. `checked` is false while that can't be told. */
+    mainnetMatch: {
+        checked: boolean;
+        deployers: {
+            deployer: string;
+            files: {
+                name: string;
+                contractId: string;
+                kind: "exact" | "partial";
+            }[];
+        }[];
+    };
+    maxContracts: number;
+    /** Plans the worker runs at once; past this, an import's plans wait their turn as `queued`. */
+    runsAtOnce: number;
+    /** The suggested contracts' new plans. USD micros; null when billing isn't linked (free daily limit). */
+    cost: {
+        plans: number;
+        runUsdMicros: number | null;
+        usdMicros: number | null;
+    };
+};
+export type ImportInput = {
+    url: string;
+    /** The `commit` the preview returned: the import plans exactly that code. */
+    commit: string;
+    /** Contract names from the preview. */
+    contracts: string[];
+    /** One of your project ids, or `"new"` (the default: a project named after the repo). */
+    project?: string;
+};
+/** `POST /projects/import`: a plan per contract (`status: "kept"` for one already in the project, `queued`
+ *  for one waiting its turn behind `runsAtOnce` others). */
+export type ImportResult = {
+    projectId: string | null;
+    commit: string;
+    plans: {
+        name: string;
+        contractId: string;
+        planId: string | null;
+        status: RunStatus | "kept";
+        cached: boolean;
+    }[];
+    /** Only when the spend guard turned plans away mid-way. */
+    notStarted?: {
+        name: string;
+        contractId: string;
+        error: string;
+    }[];
+};
+/** `added`: the account claimed it (it has a plan). `found`: a contract of the same protocol found in a member's code. */
+export type ProjectContract = {
+    contractId: string;
+    planId: string | null;
+    origin: "added" | "found";
+    role: string | null;
+    temporary: boolean;
+    [field: string]: unknown;
+};
+export type Project = {
+    id: string;
+    name: string;
+    createdAt: string;
+    contracts: ProjectContract[];
+    /** Monitoring across the contracts the account claimed in it. */
+    status: "live" | "starting" | "armed" | "partial" | "off";
+    findings: number;
+    alerts7d: number;
+    suggestions: number;
+    [field: string]: unknown;
+};
+/** A project that looks like part of another. Never merged without the account: accept or dismiss it. */
+export type MergeSuggestion = {
+    from: string;
+    into: string;
+    evidence: {
+        kind: string;
+        from: string;
+        to: string;
+        fns?: string[];
+        repo?: string;
+    };
+};
+/** `GET /projects/:id/overview`: the project, each claimed contract's plan and (with `watches`) its watches. */
+export type ProjectOverview = {
+    project: Project;
+    plans: Record<string, PlanView>;
+    planErrors: Record<string, string>;
+    watches?: Record<string, WatchesView | null>;
+};
+/** Where a contract about to be added would go: the project it fits and why. Writes nothing. */
+export type ProjectPreview = {
+    kind?: "deployed" | "prelaunch";
+    contractId: string;
+    /** The contracts it calls (a deployed one only). */
+    calls: string[];
+    suggestion: {
+        /** One of the account's project ids, or "new". */
+        project: string;
+        kind: "already" | "called-by" | "calls" | "same-deployer" | "none";
+        /** The contract of that project the link runs through. */
+        with: string | null;
+    };
+    [field: string]: unknown;
+};
+/** What a project-wide save did on one contract. */
+export type ProjectMemberResult = {
+    contractId: string;
+    planId: string;
+    result: "saved" | "remembered" | "on" | "off" | "unchanged" | "skipped" | "error";
+    error?: string;
+    /** A new webhook's signing secret, shown once; each contract signs with its own. */
+    signingSecret?: string;
+};
+/** A project's watches as one list: every row names the member plan to write through. */
+export type ProjectWatchesView = {
+    contracts: {
+        contractId: string;
+        planId: string;
+        [field: string]: unknown;
+    }[];
+    intents: (IntentWatch<unknown> & {
+        [field: string]: unknown;
+    })[];
+    counts: {
+        on: number;
+        total: number;
+    };
+    locked: number;
+    [field: string]: unknown;
+};
+/** One intent watch's activity, as the web app draws it: points, the history page, counts. */
+export type WatchActivity = {
+    window: 7 | 90;
+    asset: string | null;
+    unit: Units | null;
+    counts: {
+        total: number;
+        over: number;
+    };
+    events: {
+        t: string;
+        block: number | null;
+        txId: string;
+        fn: string | null;
+        value: string | null;
+        caller: string | null;
+        result: string | null;
+        [field: string]: unknown;
+    }[];
+    nextCursor: string | null;
+    history: "collecting" | "ready" | "failed";
+    [field: string]: unknown;
+};
+export type ActivityOptions = {
+    window?: 7 | 90;
+    /** `over`: only what crossed a rule's line. */
+    filter?: "over" | "all";
+    cursor?: string | null;
+    /** Money out: which asset. */
+    asset?: string;
+};
+/** A public fn: what it does and the intent watch covering it (null: nothing watches it). */
+export type PlanFunction = {
+    fn: string;
+    consequence: string | null;
+    description: string | null;
+    intentId: string | null;
+};
+/** One alert as email and Slack render it, and the webhook body. */
+export type AlertPreview = {
+    message: {
+        subject: string;
+        text: string;
+        slack: unknown;
+    };
+    payload: Record<string, unknown>;
+};
+/** Where a pre-launch plan's branch is now. `free`: monitoring is on, so an update costs nothing. */
+export type LatestCommit = {
+    status: "unsupported";
+} | {
+    status: "current";
+    ref: string;
+    commit: string;
+    free: boolean;
+} | {
+    status: "gone";
+    ref: string;
+    head: string;
+    free: boolean;
+} | {
+    status: "behind";
+    ref: string;
+    commit: string;
+    head: string;
+    ahead: number;
+    mode: "carried" | "focused" | "full";
+    affected: string[];
+    changed: string[];
+    free: boolean;
+};
+export type AckReason = "accepted" | "fixed" | "disagree";
+export type AckEvent = {
+    action: "acknowledge" | "change" | "reopen" | "returned";
+    title: string;
+    reason: AckReason | null;
+    note: string | null;
+    by: string | null;
+    at: string;
+};
+export type FindingNote = {
+    id: string;
+    body: string;
+    by: string | null;
+    system: boolean;
+    at: string;
+};
 export type ClientOptions = {
     baseUrl?: string;
     token: string;
@@ -399,6 +662,11 @@ export declare function createClient(opts: ClientOptions): {
         status: string;
         cached: boolean;
     }>;
+    /** A public Clarinet repo's contracts, what each would cost and where each stands. Writes and charges nothing. */
+    previewImport: (url: string) => Promise<ImportPreview>;
+    /** Plan the named contracts of a previewed repo into one project, at the preview's commit. One paid plan
+     *  per new contract (a recent plan is reused free); all refused before any starts when the balance is short. */
+    importRepo: (input: ImportInput) => Promise<ImportResult>;
     billing: () => Promise<BillingView>;
     watches: (planId: string) => Promise<WatchesView>;
     /** Set a new rule for a watch. Applies now. */
@@ -445,6 +713,183 @@ export declare function createClient(opts: ClientOptions): {
     stopMonitoring: (planId: string) => Promise<{
         ok: boolean;
     }>;
+    /** One intent watch's activity (an intent id from `watches`): what it saw and what crossed its rules. */
+    watchActivity: (planId: string, intentId: string, opts?: ActivityOptions) => Promise<WatchActivity>;
+    /** Every public fn, what it does and the watch covering it. */
+    functions: (planId: string) => Promise<PlanFunction[]>;
+    /** What a watch on a fn nobody watches yet would have seen; `collected: false` until its history is read. */
+    functionActivity: (planId: string, fn: string) => Promise<{
+        collected: false;
+    } | {
+        collected: true;
+        activity: WatchActivity;
+    }>;
+    /** A sample alert as email, Slack and the webhook get it. `example` picks the kind, else the loudest watch. */
+    alertPreview: (planId: string, example?: "money_out" | "finding") => Promise<AlertPreview>;
+    /** One asset's Money out limit, in base units. */
+    threshold: (planId: string, asset: string) => Promise<{
+        asset: string;
+        threshold: Threshold;
+    }>;
+    /** Set (or confirm) one asset's Money out limit, in base units (a digit string). Live at once. */
+    setThreshold: (planId: string, asset: string, amount: string) => Promise<{
+        asset: string;
+        threshold: Threshold;
+    }>;
+    /** Forget the failed history reads of this plan's watches and read again in the background. */
+    retryHistory: (planId: string) => Promise<{
+        ok: true;
+    }>;
+    readAlert: (alertId: string) => Promise<{
+        ok: true;
+    }>;
+    readAllAlerts: () => Promise<{
+        ok: true;
+        count: number;
+    }>;
+    /** Ask a question about Sentinel; answered from its public docs. */
+    ask: (q: string) => Promise<{
+        question: string;
+        answered: boolean;
+        answer: string;
+        sources: string[];
+        cached: boolean;
+    }>;
+    /** Label a finding for the team (`title` guards against acting on a finding that moved). Changes no verdict. */
+    acknowledge: (planId: string, finding: number, title: string, reason: AckReason, note?: string | null) => Promise<{
+        ok: true;
+        watchId?: string;
+    }>;
+    reopen: (planId: string, finding: number, title: string) => Promise<{
+        ok: true;
+    }>;
+    /** Every acknowledgement change on the contract (verified owners). */
+    ackHistory: (planId: string) => Promise<AckEvent[]>;
+    /** Your notes on one finding (verified owners). */
+    notes: (planId: string, finding: number) => Promise<FindingNote[]>;
+    addNote: (planId: string, finding: number, title: string, body: string) => Promise<{
+        note: FindingNote;
+    }>;
+    /** Run your own Clarinet test files against the plan's contract in the sandbox. */
+    tests: (planId: string, files: {
+        path: string;
+        content: string;
+    }[]) => Promise<StartedRun>;
+    /** Free compile check of an invariant harness. Starts nothing. */
+    fuzzCheck: (planId: string, harness: string) => Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    /** Fuzz the contract against your Clarity invariants in the sandbox. */
+    fuzz: (planId: string, invariants: string) => Promise<StartedRun>;
+    /** Whether a pre-launch plan's branch moved on, and what an update would review. */
+    latestCommit: (planId: string) => Promise<LatestCommit>;
+    /** Plan the branch's latest commit, or `commit` (40-hex). Free while monitoring is on, else priced as a plan. */
+    updatePlan: (planId: string, commit?: string) => Promise<{
+        planId: string;
+        status: string;
+        mode?: string;
+        existing?: boolean;
+    }>;
+    /** A plan waiting on undeployed dependencies: plan it on its own when they deploy (or not). */
+    setAutoPlan: (planId: string, auto: boolean) => Promise<{
+        auto: boolean;
+    }>;
+    /** Link code for one dependency the plan waits on (a file or repo link), or clear it with null. */
+    setLink: (planId: string, dependency: string, url: string | null) => Promise<{
+        links: {
+            id: string;
+            [field: string]: unknown;
+        }[];
+    }>;
+    /** Plan now with the linked code. Spends balance like a new plan. */
+    planLinked: (planId: string) => Promise<{
+        planId: string;
+        status: string;
+    }>;
+    /** Your own name for the contract; an empty one clears it. */
+    renameContract: (planId: string, name: string) => Promise<{
+        name: string | null;
+    }>;
+    /** Take the contract off your account: monitoring, alerts and claim. `confirm` is its contract name, typed. */
+    removeContract: (planId: string, confirm: string) => Promise<{
+        removed: true;
+        monitoringOff: boolean;
+    }>;
+    projects: () => Promise<{
+        projects: Project[];
+        suggestions: MergeSuggestion[];
+    }>;
+    project: (projectId: string) => Promise<Project>;
+    /** The project with each claimed contract's plan and, with `watches`, its watches, in one read. */
+    projectOverview: (projectId: string, opts?: {
+        watches?: boolean;
+    }) => Promise<ProjectOverview>;
+    renameProject: (projectId: string, name: string) => Promise<{
+        name: string;
+    }>;
+    /** Remove every contract you claimed in it, and the project. `confirm` is the project's name, typed. */
+    removeProject: (projectId: string, confirm: string) => Promise<{
+        removed: true;
+        contracts: number;
+    }>;
+    /** Accept (move `from`'s contracts into `into`) or dismiss a merge suggestion from `projects`. */
+    answerMergeSuggestion: (from: string, into: string, accept: boolean) => Promise<{
+        ok: true;
+        accepted: boolean;
+    }>;
+    /** Merge a project into another of yours: every contract moves; monitoring and verification stay. */
+    mergeProject: (projectId: string, into: string) => Promise<{
+        merged: true;
+        into: string;
+        contracts: number;
+    }>;
+    /** Move one contract to another of your projects, or a new one named after it (`"new"`). */
+    moveProjectContract: (projectId: string, contractId: string, into: string) => Promise<{
+        moved: true;
+        projectId: string;
+        projectRemoved: boolean;
+    }>;
+    /** A contract you claimed goes the way removeContract takes it (`confirm`: its contract name, typed); a
+     *  found one just leaves the project. */
+    removeProjectContract: (projectId: string, contractId: string, confirm?: string) => Promise<{
+        removed: true;
+        projectRemoved: boolean;
+        monitoringOff: boolean;
+    }>;
+    /** Where a contract (a deployed id or a GitHub/Gist `.clar` link) would go. Writes nothing. */
+    previewProjectContract: (projectId: string, contractId: string) => Promise<ProjectPreview>;
+    /** Claim a contract and start its plan into this project, another (`project`) or a new one (`"new"`). Spends
+     *  balance like a new plan. */
+    addProjectContract: (projectId: string, contractId: string, opts?: {
+        project?: string;
+        temporary?: boolean;
+    }) => Promise<{
+        planId: string;
+        status: string;
+        cached: boolean;
+        projectId: string;
+    }>;
+    /** Where the project's alerts go, set on each contract you claimed in it. An omitted URL clears it. */
+    setProjectDestinations: (projectId: string, dest: {
+        email?: boolean;
+        slackUrl?: string;
+        webhookUrl?: string;
+    }) => Promise<{
+        contracts: ProjectMemberResult[];
+    }>;
+    /** Monitoring on or off for every contract you claimed in the project. */
+    setProjectMonitoring: (projectId: string, on: boolean) => Promise<{
+        contracts: ProjectMemberResult[];
+        status: Project["status"];
+    }>;
+    /** The project's watches as one list; each row names the member plan the watch tools write through. */
+    projectWatches: (projectId: string) => Promise<ProjectWatchesView>;
+    /** One member's activity of an intent (`contract`: the member, default the first that holds it). */
+    projectActivity: (projectId: string, intentId: string, opts?: ActivityOptions & {
+        contract?: string;
+        fn?: string;
+    }) => Promise<WatchActivity>;
 };
 export type SentinelClient = ReturnType<typeof createClient>;
 /** A mute end `hours` out, a minute inside the 7-day limit so clock skew can't tip it over. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secondlayer/sentinel",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Sentinel from a terminal or an agent: the CLI, an MCP server and a client for your Stacks contract monitoring.",
   "license": "MIT",
   "repository": "https://runsentinel.app/docs",