@abyss-project/probe 1.0.0 → 2.0.0

package/src/api/probe-scan.application.api.ts

@@ -0,0 +1,157 @@
+// ──────────────────────────────────────────────
+// AbyssProbe APPLICATION scan API — POST /application/:applicationId/scan
+// (sync + async), GET /application/:applicationId/scan/:scanId (poll),
+// GET /application/:applicationId/scan (history/search). Mirrors
+// apps/api/src/api/controllers/probe-scan-application.controller.ts EXACTLY
+// (see that file for the full contract this client targets) — the
+// application counterpart of probe-scan.api.ts, for inter-service callers
+// (abyss-storage, external integrations) authenticating with a project API
+// key instead of a personal/org session.
+//
+// Reuses probe-scan.api.ts's `buildScanForm` (the global `FormData` + `Blob`,
+// one code path for the browser and for Node — see that file's header for what
+// a Node caller passes) and every request/response TYPE verbatim
+// (`IScanOptions`, `IListScansQuery`, `IScanResponse`, `IScanSyncResponse`,
+// `IScanAsyncResponse`, `IGetScanResponse`, `IPaginateScanResponse`) — never
+// redefined here. `organizationId` is `Omit`'d from every option/query type
+// below: unlike the personal/org route's `?organization_id=` override, an
+// application caller's scope is entirely its `:applicationId` URL segment,
+// resolved server-side by ProbeApplicationMiddleware (round-trips to
+// abyss-main) — there is no scope query param to send.
+//
+// `authHeaderApplication` is kept LOCAL and unexported, same convention as
+// the personal/org client's own `authHeader` (see probe-scan.api.ts's header
+// comment) — it sends `API_KEY_APPLICATION_HEADER` (`abyss-api-key-
+// application`, imported from this package's root) instead of the personal
+// `abyss-api-key` header.
+// ──────────────────────────────────────────────
+
+import { AbyssProbeCore, API_KEY_APPLICATION_HEADER } from '..';
+import { ProbeScanMode } from '../types';
+import type {
+  IScanOptions,
+  IListScansQuery,
+  IScanResponse,
+  IScanSyncResponse,
+  IScanAsyncResponse,
+  IGetScanResponse,
+  IPaginateScanResponse,
+} from '../types';
+import { buildScanForm } from './probe-scan.api';
+import type { ProbeScanFileInput } from './probe-scan.api';
+
+function authHeaderApplication(applicationApiKey?: string): Record<string, string> {
+  return applicationApiKey ? { [API_KEY_APPLICATION_HEADER]: applicationApiKey } : {};
+}
+
+/**
+ * Turn a request/query options object into axios `params`: drops
+ * undefined/null and ISO-stringifies `Date`s. No key-renaming here (unlike
+ * probe-scan.api.ts#serializeProbeQuery's `organizationId` -> `organization_id`
+ * rename) — an application call never carries `organizationId` (`Omit`'d
+ * from every option/query type in this file), so there is nothing to rename.
+ */
+function serializeProbeQuery<T extends object>(query: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(query as Record<string, unknown>)) {
+    if (value === undefined || value === null) continue;
+    out[key] = value instanceof Date ? value.toISOString() : value;
+  }
+  return out;
+}
+
+/**
+ * `POST /application/:applicationId/scan` — SYNC by default, ASYNC when
+ * `options.mode = ProbeScanMode.ASYNC` (identical contract to {@link
+ * ../probe-scan.api.scan | the personal/org `scan`} — see that function's
+ * doc comment for the full sequence). `mode` travels as a query param;
+ * `context` (JSON-encoded) and `callbackUrl` travel as multipart text fields
+ * alongside the file.
+ *
+ * Returns the SYNC (200, verdict inline) or ASYNC (202, `{ scanId, status:
+ * 'queued' }`) shape depending on `options.mode` — see {@link IScanResponse}.
+ * Prefer {@link scanSyncApplication} / {@link scanAsyncApplication} for a
+ * precisely-typed return instead of the union.
+ */
+export const scanApplication = async (
+  applicationId: string,
+  file: ProbeScanFileInput,
+  options: Omit<IScanOptions, 'organizationId'> = {},
+  applicationApiKey?: string,
+): Promise<IScanResponse> => {
+  const form = buildScanForm(file, options);
+  return (
+    await AbyssProbeCore.axios.post<IScanResponse>(`application/${applicationId}/scan`, form, {
+      params: serializeProbeQuery({ mode: options.mode }),
+      headers: authHeaderApplication(applicationApiKey),
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    })
+  ).data;
+};
+
+/** {@link scanApplication}, forced to `mode: sync` — HTTP 200, verdict returned inline. */
+export const scanSyncApplication = async (
+  applicationId: string,
+  file: ProbeScanFileInput,
+  options: Omit<IScanOptions, 'organizationId' | 'mode' | 'callbackUrl'> = {},
+  applicationApiKey?: string,
+): Promise<IScanSyncResponse> =>
+  scanApplication(
+    applicationId,
+    file,
+    { ...options, mode: ProbeScanMode.SYNC },
+    applicationApiKey,
+  ) as Promise<IScanSyncResponse>;
+
+/** {@link scanApplication}, forced to `mode: async` — HTTP 202, job queued. */
+export const scanAsyncApplication = async (
+  applicationId: string,
+  file: ProbeScanFileInput,
+  options: Omit<IScanOptions, 'organizationId' | 'mode'> = {},
+  applicationApiKey?: string,
+): Promise<IScanAsyncResponse> =>
+  scanApplication(
+    applicationId,
+    file,
+    { ...options, mode: ProbeScanMode.ASYNC },
+    applicationApiKey,
+  ) as Promise<IScanAsyncResponse>;
+
+/**
+ * `GET /application/:applicationId/scan/:scanId` — poll the queued ->
+ * scanning -> done/error progression of an ASYNC scan (also answers for a
+ * SYNC scan's row). Cross-tenant guarded server-side by a direct
+ * `applicationId` column comparison (404, never 403) — needs no scope
+ * argument beyond `applicationId` itself, the scanId alone determines the
+ * rest.
+ */
+export const getScanApplication = async (
+  applicationId: string,
+  scanId: string,
+  applicationApiKey?: string,
+): Promise<IGetScanResponse> =>
+  (
+    await AbyssProbeCore.axios.get<IGetScanResponse>(
+      `application/${applicationId}/scan/${scanId}`,
+      { headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;
+
+/**
+ * `GET /application/:applicationId/scan` — paginated scan history/search for
+ * the calling application, newest first. Same filters as the personal/org
+ * `GET /scan` minus `organizationId` (see {@link IListScansQuery}) — the
+ * `:applicationId` URL segment is already the entire scope.
+ */
+export const listScansApplication = async (
+  applicationId: string,
+  query: Omit<IListScansQuery, 'organizationId'> = {},
+  applicationApiKey?: string,
+): Promise<IPaginateScanResponse> =>
+  (
+    await AbyssProbeCore.axios.get<IPaginateScanResponse>(`application/${applicationId}/scan`, {
+      params: serializeProbeQuery(query),
+      headers: authHeaderApplication(applicationApiKey),
+    })
+  ).data;

package/src/api/probe-usage.api.ts

@@ -0,0 +1,47 @@
+// ──────────────────────────────────────────────
+// AbyssProbe usage API — WS5-3 (AbyssProbe UX rework). `GET /usage`: current
+// ACCOUNT_AV_SCAN_UNITS ("tokens") used/limit/remaining for the caller's
+// scope, via the same billing check the quota gate itself already uses (see
+// apps/api/src/utils/probe-scan-billing.util.ts#getProbeScanUsage). Mirrors
+// apps/api/src/api/controllers/probe-usage.controller.ts EXACTLY. No
+// `probe/` path prefix — `@Controller({ prefixPath: '/usage' })` mounts
+// directly at `usage`.
+//
+// See probe-usage.application.api.ts for the application/API-key-auth
+// counterpart (`/application/:applicationId/usage`, Phase 3a).
+// ──────────────────────────────────────────────
+
+import { AbyssProbeCore } from '..';
+import type { IProbeUsageScopeQuery, IProbeUsageResponse } from '../types';
+
+const DEFAULT_API_KEY_HEADER = 'abyss-api-key';
+
+function authHeader(apiKey?: string): Record<string, string> {
+  return apiKey ? { [DEFAULT_API_KEY_HEADER]: apiKey } : {};
+}
+
+/** Renames `organizationId` to the wire's `organization_id` (see probe-scan.api.ts). */
+function serializeProbeQuery<T extends object>(query: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(query as Record<string, unknown>)) {
+    if (value === undefined || value === null) continue;
+    const wireKey = key === 'organizationId' ? 'organization_id' : key;
+    out[wireKey] = value;
+  }
+  return out;
+}
+
+/**
+ * `GET /usage` — current ACCOUNT_AV_SCAN_UNITS consumption for the caller's
+ * scope (personal by default, `organizationId` for an organization scope).
+ */
+export const getProbeUsage = async (
+  scope: IProbeUsageScopeQuery = {},
+  apiKey?: string,
+): Promise<IProbeUsageResponse> =>
+  (
+    await AbyssProbeCore.axios.get<IProbeUsageResponse>('usage', {
+      params: serializeProbeQuery(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;

package/src/api/probe-usage.application.api.ts

@@ -0,0 +1,25 @@
+// ──────────────────────────────────────────────
+// AbyssProbe APPLICATION usage API — WS5-3 (AbyssProbe UX rework). `GET
+// /application/:applicationId/usage`: current ACCOUNT_AV_SCAN_UNITS
+// consumption for the calling application's resolved billing organization.
+// Mirrors apps/api/src/api/controllers/probe-usage-application.controller.ts
+// EXACTLY — the application counterpart of probe-usage.api.ts.
+// ──────────────────────────────────────────────
+
+import { AbyssProbeCore, API_KEY_APPLICATION_HEADER } from '..';
+import type { IProbeUsageResponse } from '../types';
+
+function authHeaderApplication(applicationApiKey?: string): Record<string, string> {
+  return applicationApiKey ? { [API_KEY_APPLICATION_HEADER]: applicationApiKey } : {};
+}
+
+/** `GET /application/:applicationId/usage` — current ACCOUNT_AV_SCAN_UNITS consumption for the calling application. */
+export const getProbeUsageApplication = async (
+  applicationId: string,
+  applicationApiKey?: string,
+): Promise<IProbeUsageResponse> =>
+  (
+    await AbyssProbeCore.axios.get<IProbeUsageResponse>(`application/${applicationId}/usage`, {
+      headers: authHeaderApplication(applicationApiKey),
+    })
+  ).data;

package/src/api/probe-webhook.api.test.ts

@@ -0,0 +1,17 @@
+// Type-level compile test for the probe-webhook api surface.
+// No jest runner in this SDK package; compile guard only.
+// Run: npx tsc --noEmit (from packages/abyss_probe_core), or `npm run build`.
+
+import * as api from './probe-webhook.api';
+
+// All three functions must be exported — deliberately no update/reset-secret
+// (see probe-webhook.controller.ts's header comment on the small CRUD surface).
+const _create: typeof api.createProbeWebhook = api.createProbeWebhook;
+const _list: typeof api.listProbeWebhook = api.listProbeWebhook;
+const _delete: typeof api.deleteProbeWebhook = api.deleteProbeWebhook;
+
+void _create;
+void _list;
+void _delete;
+
+export {};

package/src/api/probe-webhook.api.ts

@@ -0,0 +1,119 @@
+// ──────────────────────────────────────────────
+// AbyssProbe webhook subscription API — CRUD over registered `probe_webhooks`
+// (create / list / delete / update, + paginated delivery history — mirrors
+// apps/api/src/api/controllers/probe-webhook.controller.ts EXACTLY, see that
+// file's header comment). No `probe/` path prefix — `@Controller({
+// prefixPath: '/webhook' })` mounts directly at `webhook`.
+//
+// See probe-webhook.application.api.ts for the application/API-key-auth
+// counterpart of this client (`/application/:applicationId/webhook...`,
+// Phase 3a) — it reuses every request/response type verbatim; only the URL
+// prefix, the extra `applicationId` argument, and the auth header differ.
+// ──────────────────────────────────────────────
+
+import { AbyssProbeCore } from '..';
+import type {
+  ICreateProbeWebhookBody,
+  IUpdateProbeWebhookBody,
+  IProbeWebhookScopeQuery,
+  IListProbeWebhookDeliveriesQuery,
+  ICreateProbeWebhookResponse,
+  IListProbeWebhookResponse,
+  IDeleteProbeWebhookResponse,
+  IUpdateProbeWebhookResponse,
+  IListProbeWebhookDeliveriesResponse,
+} from '../types';
+
+const DEFAULT_API_KEY_HEADER = 'abyss-api-key';
+
+function authHeader(apiKey?: string): Record<string, string> {
+  return apiKey ? { [DEFAULT_API_KEY_HEADER]: apiKey } : {};
+}
+
+/** Renames `organizationId` to the wire's `organization_id` (see probe-scan.api.ts). */
+function serializeProbeQuery<T extends object>(query: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(query as Record<string, unknown>)) {
+    if (value === undefined || value === null) continue;
+    const wireKey = key === 'organizationId' ? 'organization_id' : key;
+    out[wireKey] = value instanceof Date ? value.toISOString() : value;
+  }
+  return out;
+}
+
+/**
+ * `POST /webhook` — register a callbackUrl for the caller's scope. The
+ * response's `secret` field (HMAC signing secret) is returned ONLY here —
+ * store it immediately, it cannot be re-revealed later.
+ */
+export const createProbeWebhook = async (
+  body: ICreateProbeWebhookBody,
+  scope: IProbeWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<ICreateProbeWebhookResponse> =>
+  (
+    await AbyssProbeCore.axios.post<ICreateProbeWebhookResponse>('webhook', body, {
+      params: serializeProbeQuery(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+/** `GET /webhook` — flat, scope-filtered list (not paginated — bounded by WEBHOOK_MAX_PER_SCOPE server-side). */
+export const listProbeWebhook = async (
+  scope: IProbeWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IListProbeWebhookResponse> =>
+  (
+    await AbyssProbeCore.axios.get<IListProbeWebhookResponse>('webhook', {
+      params: serializeProbeQuery(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+/** `DELETE /webhook/:webhookId`. */
+export const deleteProbeWebhook = async (
+  webhookId: string,
+  scope: IProbeWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IDeleteProbeWebhookResponse> =>
+  (
+    await AbyssProbeCore.axios.delete<IDeleteProbeWebhookResponse>(`webhook/${webhookId}`, {
+      params: serializeProbeQuery(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+/**
+ * `PATCH /webhook/:webhookId` (WS5-5) — edit `callbackUrl` and/or `active`.
+ * At least one field is required. Scoped like {@link deleteProbeWebhook}
+ * (404, never 403, for a webhookId outside the resolved scope). The response
+ * includes `secret` — re-displayable now, see {@link IProbeWebhook}.
+ */
+export const updateProbeWebhook = async (
+  webhookId: string,
+  body: IUpdateProbeWebhookBody,
+  scope: IProbeWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IUpdateProbeWebhookResponse> =>
+  (
+    await AbyssProbeCore.axios.patch<IUpdateProbeWebhookResponse>(`webhook/${webhookId}`, body, {
+      params: serializeProbeQuery(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+/**
+ * `GET /webhook/:webhookId/deliveries` (WS5-6) — paginated delivery-attempt
+ * history for one registered webhook. Scoped like {@link deleteProbeWebhook}.
+ */
+export const listProbeWebhookDeliveries = async (
+  webhookId: string,
+  query: IListProbeWebhookDeliveriesQuery = {},
+  apiKey?: string,
+): Promise<IListProbeWebhookDeliveriesResponse> =>
+  (
+    await AbyssProbeCore.axios.get<IListProbeWebhookDeliveriesResponse>(
+      `webhook/${webhookId}/deliveries`,
+      { params: serializeProbeQuery(query), headers: authHeader(apiKey) },
+    )
+  ).data;

package/src/api/probe-webhook.application.api.test.ts

@@ -0,0 +1,18 @@
+// Type-level compile test for the probe-webhook APPLICATION api surface.
+// No jest runner in this SDK package; compile guard only (mirrors
+// probe-webhook.api.test.ts).
+// Run: npx tsc --noEmit (from packages/abyss_probe_core), or `npm run build`.
+
+import * as api from './probe-webhook.application.api';
+
+// All three functions must be exported — deliberately no update/reset-secret
+// (see probe-webhook.api.ts's header comment on the small CRUD surface).
+const _create: typeof api.createProbeWebhookApplication = api.createProbeWebhookApplication;
+const _list: typeof api.listProbeWebhookApplication = api.listProbeWebhookApplication;
+const _delete: typeof api.deleteProbeWebhookApplication = api.deleteProbeWebhookApplication;
+
+void _create;
+void _list;
+void _delete;
+
+export {};

package/src/api/probe-webhook.application.api.ts

@@ -0,0 +1,141 @@
+// ──────────────────────────────────────────────
+// AbyssProbe APPLICATION webhook subscription API — CRUD over registered
+// `probe_webhooks` owned by a calling application (create / list / delete /
+// update, + paginated delivery history — same surface as the personal/org
+// client, see probe-webhook.api.ts's header comment). Mirrors
+// apps/api/src/api/controllers/probe-webhook-application.controller.ts
+// EXACTLY — the application counterpart of probe-webhook.api.ts, for
+// inter-service callers (abyss-storage, external integrations)
+// authenticating with a project API key instead of a personal/org session.
+//
+// Reuses every request/response TYPE verbatim (`ICreateProbeWebhookBody`,
+// `ICreateProbeWebhookResponse`, `IListProbeWebhookResponse`,
+// `IDeleteProbeWebhookResponse`, `IUpdateProbeWebhookBody`,
+// `IUpdateProbeWebhookResponse`, `IListProbeWebhookDeliveriesQuery`,
+// `IListProbeWebhookDeliveriesResponse`) — never redefined here. No scope
+// argument/query on any of these calls (unlike the personal/org client's
+// `IProbeWebhookScopeQuery`) — an application caller's scope is entirely its
+// `:applicationId` URL segment, resolved server-side by
+// ProbeApplicationMiddleware; there is nothing to select between.
+//
+// `authHeaderApplication` is kept LOCAL and unexported, same convention as
+// the personal/org client's own `authHeader` — it sends
+// `API_KEY_APPLICATION_HEADER` (`abyss-api-key-application`, imported from
+// this package's root) instead of the personal `abyss-api-key` header.
+// ──────────────────────────────────────────────
+
+import { AbyssProbeCore, API_KEY_APPLICATION_HEADER } from '..';
+import type {
+  ICreateProbeWebhookBody,
+  IUpdateProbeWebhookBody,
+  IListProbeWebhookDeliveriesQuery,
+  ICreateProbeWebhookResponse,
+  IListProbeWebhookResponse,
+  IDeleteProbeWebhookResponse,
+  IUpdateProbeWebhookResponse,
+  IListProbeWebhookDeliveriesResponse,
+} from '../types';
+
+function authHeaderApplication(applicationApiKey?: string): Record<string, string> {
+  return applicationApiKey ? { [API_KEY_APPLICATION_HEADER]: applicationApiKey } : {};
+}
+
+/** Renames nothing (no `organizationId` ever travels on an application call) — drops undefined/null and ISO-stringifies `Date`s, mirroring probe-scan.application.api.ts's own local helper. */
+function serializeProbeQuery<T extends object>(query: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(query as Record<string, unknown>)) {
+    if (value === undefined || value === null) continue;
+    out[key] = value instanceof Date ? value.toISOString() : value;
+  }
+  return out;
+}
+
+/**
+ * `POST /application/:applicationId/webhook` — register a callbackUrl owned
+ * by the calling application. The response's `secret` field (HMAC signing
+ * secret) is returned ONLY here — store it immediately, it cannot be
+ * re-revealed later.
+ */
+export const createProbeWebhookApplication = async (
+  applicationId: string,
+  body: ICreateProbeWebhookBody,
+  applicationApiKey?: string,
+): Promise<ICreateProbeWebhookResponse> =>
+  (
+    await AbyssProbeCore.axios.post<ICreateProbeWebhookResponse>(
+      `application/${applicationId}/webhook`,
+      body,
+      { headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;
+
+/**
+ * `GET /application/:applicationId/webhook` — flat list of the calling
+ * application's own webhooks (not paginated — bounded by
+ * WEBHOOK_MAX_PER_SCOPE server-side).
+ */
+export const listProbeWebhookApplication = async (
+  applicationId: string,
+  applicationApiKey?: string,
+): Promise<IListProbeWebhookResponse> =>
+  (
+    await AbyssProbeCore.axios.get<IListProbeWebhookResponse>(
+      `application/${applicationId}/webhook`,
+      { headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;
+
+/**
+ * `DELETE /application/:applicationId/webhook/:webhookId` — cross-tenant
+ * guarded server-side by a direct `applicationId` comparison (404, never
+ * 403).
+ */
+export const deleteProbeWebhookApplication = async (
+  applicationId: string,
+  webhookId: string,
+  applicationApiKey?: string,
+): Promise<IDeleteProbeWebhookResponse> =>
+  (
+    await AbyssProbeCore.axios.delete<IDeleteProbeWebhookResponse>(
+      `application/${applicationId}/webhook/${webhookId}`,
+      { headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;
+
+/**
+ * `PATCH /application/:applicationId/webhook/:webhookId` (WS5-5) — edit
+ * `callbackUrl` and/or `active` on a webhook owned by the calling
+ * application. Cross-tenant guarded server-side (404, never 403). The
+ * response includes `secret` — re-displayable now, see {@link IProbeWebhook}.
+ */
+export const updateProbeWebhookApplication = async (
+  applicationId: string,
+  webhookId: string,
+  body: IUpdateProbeWebhookBody,
+  applicationApiKey?: string,
+): Promise<IUpdateProbeWebhookResponse> =>
+  (
+    await AbyssProbeCore.axios.patch<IUpdateProbeWebhookResponse>(
+      `application/${applicationId}/webhook/${webhookId}`,
+      body,
+      { headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;
+
+/**
+ * `GET /application/:applicationId/webhook/:webhookId/deliveries` (WS5-6) —
+ * paginated delivery-attempt history for one webhook owned by the calling
+ * application. Cross-tenant guarded server-side (404, never 403).
+ */
+export const listProbeWebhookDeliveriesApplication = async (
+  applicationId: string,
+  webhookId: string,
+  query: Omit<IListProbeWebhookDeliveriesQuery, 'organizationId'> = {},
+  applicationApiKey?: string,
+): Promise<IListProbeWebhookDeliveriesResponse> =>
+  (
+    await AbyssProbeCore.axios.get<IListProbeWebhookDeliveriesResponse>(
+      `application/${applicationId}/webhook/${webhookId}/deliveries`,
+      { params: serializeProbeQuery(query), headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;

package/src/constants/index.ts

@@ -0,0 +1 @@
+export {};