@signa-so/sdk 0.2.1 → 0.4.0

package/dist/resources/trademarks.js

@@ -4,26 +4,41 @@ export class Trademarks extends BaseResource {
     /**
      * Retrieve a single trademark by ID.
      *
+     * The full detail tier (owners, classifications, attorneys, media,
+     * priorities, proceedings, Madrid coverage) is always returned inline.
+     * Pass `include: ['history']` to embed the 50 most recent prosecution
+     * events alongside the detail object.
+     *
      * ```typescript
      * const tm = await signa.trademarks.retrieve('tm_abc123');
-     * const tm = await signa.trademarks.retrieve('tm_abc123', { include: ['owners', 'history'] });
+     * const tm = await signa.trademarks.retrieve('tm_abc123', { include: ['history'] });
      * ```
      */
     async retrieve(id, params, options) {
         this._validateId(id);
         return this._get(`/v1/trademarks/${encodeURIComponent(id)}`, {
             include: params?.include,
-            fields: params?.fields,
         }, options);
     }
     /**
-     * List trademarks with filters. At least one filter is required.
+     * List trademarks with filters via GET. At least one filter or `q` query is required.
      * Returns a SignaList supporting auto-pagination.
      *
+     * Now supports text search via `q`, sorting via `sort`, and search options
+     * like `strategies`, `include_total`, `highlights`, and `include_timing`.
+     *
      * ```typescript
-     * const page = await signa.trademarks.list({ jurisdiction_code: 'US', status: 'registered' });
+     * // Filter-only (sorted by -filing_date by default)
+     * const page = await signa.trademarks.list({ jurisdictions: ['US'], status_primary: 'active' });
+     *
+     * // Text search with filters
+     * const results = await signa.trademarks.list({ q: 'SIGNA', jurisdictions: ['US'] });
+     *
+     * // Explicit sort
+     * const sorted = await signa.trademarks.list({ offices: ['uspto'], sort: '-registration_date' });
      *
-     * for await (const tm of signa.trademarks.list({ jurisdiction_code: 'US' })) {
+     * // Auto-pagination
+     * for await (const tm of signa.trademarks.list({ jurisdictions: ['US'] })) {
      *   console.log(tm.mark_text);
      * }
      * ```
@@ -35,6 +50,39 @@ export class Trademarks extends BaseResource {
         const firstPage = await fetchPage(params?.cursor);
         return createList(firstPage, fetchPage);
     }
+    /**
+     * Search trademarks via POST with a JSON body. Use this for complex queries
+     * with structured filters, aggregations, strategies, or ranking profiles.
+     *
+     * This replaces the old `signa.search.query()` method. The endpoint is
+     * `POST /v1/trademarks` (the old `/v1/trademarks/search` is deprecated).
+     *
+     * ```typescript
+     * const results = await signa.trademarks.search({
+     *   query: 'SIGNA',
+     *   strategies: ['exact', 'phonetic'],
+     *   filters: { jurisdictions: ['US'], nice_classes: [9, 42] },
+     *   options: { aggregations: ['status_stage', 'office_code'] },
+     * });
+     * console.log(results.aggregations);
+     * console.log(results.search_meta);
+     *
+     * // Filter-only POST (no text query)
+     * const filtered = await signa.trademarks.search({
+     *   filters: { offices: ['uspto'], status_primary: 'active' },
+     *   sort: '-filing_date',
+     *   options: { include_total: true },
+     * });
+     * ```
+     */
+    async search(params, options) {
+        const body = { ...params };
+        const response = await this._post('/v1/trademarks', body, options);
+        return createList(response, async (cursor) => {
+            const nextBody = { ...params, cursor };
+            return this._post('/v1/trademarks', nextBody, options);
+        });
+    }
     /**
      * List event history for a trademark.
      *

package/dist/resources/trademarks.js.map

@@ -1 +1 @@
-{"version":3,"file":"trademarks.js","sourceRoot":"","sources":["../../src/resources/trademarks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"trademarks.js","sourceRoot":"","sources":["../../src/resources/trademarks.ts"],"names":[],"mappings":"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"}

package/dist/resources/watches.d.ts

@@ -1,18 +1,65 @@
 import { BaseResource } from '../resource.js';
 import { type SignaList } from '../pagination.js';
-import type { Watch, Alert, DeletedResponse, WatchCreateParams, WatchUpdateParams, WatchListParams, AlertListParams, RequestOptions } from '../types.js';
+import type { Watch, Alert, DeletedResponse, WatchCreateParams, WatchCreateQueryParams, WatchUpdateParams, WatchListParams, WatchReplayParams, WatchPreviewParams, WatchPreviewResponse, WatchBulkParams, WatchDiagnostics, WatchDiagnosticsParams, AlertListParams, RequestOptions } from '../types.js';
+/**
+ * Watch management — monitoring v1 (TSK-111).
+ *
+ * Five watch types compile to one query shape (VAL-PRODUCT-001):
+ * `'mark' | 'portfolio' | 'owner' | 'class' | 'similarity'`. `query.match`
+ * is rejected in ANY form (object or string) — use `filters.ownerId`,
+ * `filters.trademarkIds`, `filters.niceClasses` for scoping and
+ * `score_threshold` for similarity precision. See {@link WatchQuery} and
+ * the watches guide for worked examples.
+ */
 export declare class Watches extends BaseResource {
-    /** Create a watch. */
-    create(body: WatchCreateParams, options?: RequestOptions): Promise<Watch>;
-    /** List organization's watches. */
+    /** Create a watch (or hydrate from a saved search via `?from_saved_search=`). */
+    create(body: WatchCreateParams, options?: RequestOptions & {
+        query?: WatchCreateQueryParams;
+    }): Promise<Watch>;
+    /** List watches for the calling org (cursor pagination, max 100/page). */
     list(params?: WatchListParams, options?: RequestOptions): Promise<SignaList<Watch>>;
-    /** Retrieve a watch. */
+    /** Retrieve a watch (`alert_count_24h` populated). */
     retrieve(id: string, options?: RequestOptions): Promise<Watch>;
-    /** Update a watch. */
+    /** Update a watch (PATCH — partial body). */
     update(id: string, body: WatchUpdateParams, options?: RequestOptions): Promise<Watch>;
-    /** Soft-delete a watch. */
+    /** Soft-delete a watch (sets `deleted_at`). */
     delete(id: string, options?: RequestOptions): Promise<DeletedResponse>;
-    /** List alerts for a specific watch. */
-    alerts(id: string, params?: Omit<AlertListParams, 'watch_id'>, options?: RequestOptions): Promise<SignaList<Alert>>;
+    /** Pause evaluation. The watch is preserved; no alerts fire until resumed. */
+    pause(id: string, options?: RequestOptions): Promise<Watch>;
+    /** Resume a paused watch. */
+    resume(id: string, options?: RequestOptions): Promise<Watch>;
+    /**
+     * Bump `evaluation_epoch` to trigger a full re-evaluation across watched
+     * offices. Requires the `watches:admin` scope. Returns 409 if the
+     * evaluator currently holds the per-(watch, office) lease (15-min stale
+     * takeover).
+     *
+     * v1 accepts an empty body only — `from_date` (historical replay) is
+     * reserved for v1.1 and the server rejects it with 400.
+     */
+    replay(id: string, body?: WatchReplayParams, options?: RequestOptions): Promise<Watch>;
+    /**
+     * Dry-run a watch query — returns the count of trademarks that would have
+     * alerted if this query had been a live watch over the last
+     * `trial_window_days` (default 7). Does not write to the DB
+     * (VAL-API-011).
+     */
+    preview(body: WatchPreviewParams, options?: RequestOptions): Promise<WatchPreviewResponse>;
+    /** Bulk-create up to 100 watches. Counts against the per-plan resource quota. */
+    bulk(body: WatchBulkParams, options?: RequestOptions): Promise<Watch[]>;
+    /**
+     * Self-service diagnostics for a single (watch, trademark) pair.
+     * Returns an 11-field explainable trace — see the
+     * [diagnostics docs](https://docs.signa.so/api-reference/monitoring/watches/diagnostics)
+     * for the full schema and `reason` enum walk-order.
+     *
+     * Required scope: `portfolios:manage`. Cross-org or missing references
+     * return 404.
+     */
+    diagnostics(watchId: string, params: WatchDiagnosticsParams, options?: RequestOptions): Promise<WatchDiagnostics>;
+    /** List alerts scoped to a single watch (cursor pagination). */
+    listAlerts(watchId: string, params?: AlertListParams, options?: RequestOptions): Promise<SignaList<Alert>>;
+    /** @internal Build a query string from a flat params object. */
+    private _buildQS;
 }
 //# sourceMappingURL=watches.d.ts.map

package/dist/resources/watches.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watches.d.ts","sourceRoot":"","sources":["../../src/resources/watches.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EACV,KAAK,EACL,KAAK,EACL,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,qBAAa,OAAQ,SAAQ,YAAY;IACvC,sBAAsB;IAChB,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC;IAI/E,mCAAmC;IAC7B,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAezF,wBAAwB;IAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC;IAKpE,sBAAsB;IAChB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC;IAK3F,2BAA2B;IACrB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAK5E,wCAAwC;IAClC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;CAe1H"}
+{"version":3,"file":"watches.d.ts","sourceRoot":"","sources":["../../src/resources/watches.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EACV,KAAK,EACL,KAAK,EACL,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,cAAc,EACf,MAAM,aAAa,CAAC;AAErB;;;;;;;;;GASG;AACH,qBAAa,OAAQ,SAAQ,YAAY;IACvC,iFAAiF;IAC3E,MAAM,CACV,IAAI,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,KAAK,CAAC,EAAE,sBAAsB,CAAA;KAAE,GAC5D,OAAO,CAAC,KAAK,CAAC;IAQjB,0EAA0E;IACpE,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAOzF,sDAAsD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC;IAKpE,6CAA6C;IACvC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC;IAK3F,+CAA+C;IACzC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAK5E,8EAA8E;IACxE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC;IAKjE,6BAA6B;IACvB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC;IAKlE;;;;;;;;OAQG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE,iBAAiB,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,KAAK,CAAC;IAKjB;;;;;OAKG;IACG,OAAO,CACX,IAAI,EAAE,kBAAkB,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,oBAAoB,CAAC;IAIhC,iFAAiF;IAC3E,IAAI,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAS7E;;;;;;;;OAQG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,sBAAsB,EAC9B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,gBAAgB,CAAC;IAY5B,gEAAgE;IAC1D,UAAU,CACd,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAY5B,gEAAgE;IAChE,OAAO,CAAC,QAAQ;CAQjB"}

package/dist/resources/watches.js

@@ -1,35 +1,114 @@
 import { BaseResource } from '../resource.js';
 import { createList } from '../pagination.js';
+/**
+ * Watch management — monitoring v1 (TSK-111).
+ *
+ * Five watch types compile to one query shape (VAL-PRODUCT-001):
+ * `'mark' | 'portfolio' | 'owner' | 'class' | 'similarity'`. `query.match`
+ * is rejected in ANY form (object or string) — use `filters.ownerId`,
+ * `filters.trademarkIds`, `filters.niceClasses` for scoping and
+ * `score_threshold` for similarity precision. See {@link WatchQuery} and
+ * the watches guide for worked examples.
+ */
 export class Watches extends BaseResource {
-    /** Create a watch. */
+    /** Create a watch (or hydrate from a saved search via `?from_saved_search=`). */
     async create(body, options) {
-        return this._post('/v1/watches', body, options);
+        const { query, ...restOpts } = options ?? {};
+        const path = query?.from_saved_search
+            ? `/v1/watches${this._buildQS({ from_saved_search: query.from_saved_search })}`
+            : '/v1/watches';
+        return this._post(path, body, restOpts);
     }
-    /** List organization's watches. */
+    /** List watches for the calling org (cursor pagination, max 100/page). */
     async list(params, options) {
-        const response = await this._getListResponse('/v1/watches', params, options);
-        return createList(response, (cursor) => this._getListResponse('/v1/watches', { ...params, cursor }, options));
+        const fetchPage = async (cursor) => this._getListResponse('/v1/watches', { ...params, cursor }, options);
+        const firstPage = await fetchPage(params?.cursor);
+        return createList(firstPage, fetchPage);
     }
-    /** Retrieve a watch. */
+    /** Retrieve a watch (`alert_count_24h` populated). */
     async retrieve(id, options) {
         this._validateId(id);
         return this._get(`/v1/watches/${encodeURIComponent(id)}`, undefined, options);
     }
-    /** Update a watch. */
+    /** Update a watch (PATCH — partial body). */
     async update(id, body, options) {
         this._validateId(id);
         return this._patch(`/v1/watches/${encodeURIComponent(id)}`, body, options);
     }
-    /** Soft-delete a watch. */
+    /** Soft-delete a watch (sets `deleted_at`). */
     async delete(id, options) {
         this._validateId(id);
         return this._delete(`/v1/watches/${encodeURIComponent(id)}`, options);
     }
-    /** List alerts for a specific watch. */
-    async alerts(id, params, options) {
+    /** Pause evaluation. The watch is preserved; no alerts fire until resumed. */
+    async pause(id, options) {
         this._validateId(id);
-        const response = await this._getListResponse(`/v1/watches/${encodeURIComponent(id)}/alerts`, params, options);
-        return createList(response, (cursor) => this._getListResponse(`/v1/watches/${encodeURIComponent(id)}/alerts`, { ...params, cursor }, options));
+        return this._post(`/v1/watches/${encodeURIComponent(id)}/pause`, {}, options);
+    }
+    /** Resume a paused watch. */
+    async resume(id, options) {
+        this._validateId(id);
+        return this._post(`/v1/watches/${encodeURIComponent(id)}/resume`, {}, options);
+    }
+    /**
+     * Bump `evaluation_epoch` to trigger a full re-evaluation across watched
+     * offices. Requires the `watches:admin` scope. Returns 409 if the
+     * evaluator currently holds the per-(watch, office) lease (15-min stale
+     * takeover).
+     *
+     * v1 accepts an empty body only — `from_date` (historical replay) is
+     * reserved for v1.1 and the server rejects it with 400.
+     */
+    async replay(id, body, options) {
+        this._validateId(id);
+        return this._post(`/v1/watches/${encodeURIComponent(id)}/replay`, body ?? {}, options);
+    }
+    /**
+     * Dry-run a watch query — returns the count of trademarks that would have
+     * alerted if this query had been a live watch over the last
+     * `trial_window_days` (default 7). Does not write to the DB
+     * (VAL-API-011).
+     */
+    async preview(body, options) {
+        return this._post('/v1/watches/preview', body, options);
+    }
+    /** Bulk-create up to 100 watches. Counts against the per-plan resource quota. */
+    async bulk(body, options) {
+        const res = await this._post('/v1/watches/bulk', body, options);
+        return res.data;
+    }
+    /**
+     * Self-service diagnostics for a single (watch, trademark) pair.
+     * Returns an 11-field explainable trace — see the
+     * [diagnostics docs](https://docs.signa.so/api-reference/monitoring/watches/diagnostics)
+     * for the full schema and `reason` enum walk-order.
+     *
+     * Required scope: `portfolios:manage`. Cross-org or missing references
+     * return 404.
+     */
+    async diagnostics(watchId, params, options) {
+        this._validateId(watchId);
+        if (!params || typeof params.trademarkId !== 'string' || !params.trademarkId) {
+            throw new Error('diagnostics requires { trademarkId } (a tm_* ID).');
+        }
+        return this._get(`/v1/watches/${encodeURIComponent(watchId)}/diagnostics`, { trademark_id: params.trademarkId }, options);
+    }
+    /** List alerts scoped to a single watch (cursor pagination). */
+    async listAlerts(watchId, params, options) {
+        this._validateId(watchId);
+        const fetchPage = async (cursor) => this._getListResponse(`/v1/watches/${encodeURIComponent(watchId)}/alerts`, { ...params, cursor }, options);
+        const firstPage = await fetchPage(params?.cursor);
+        return createList(firstPage, fetchPage);
+    }
+    /** @internal Build a query string from a flat params object. */
+    _buildQS(params) {
+        const entries = [];
+        for (const [k, v] of Object.entries(params)) {
+            if (v === undefined || v === null)
+                continue;
+            entries.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+        }
+        return entries.length ? `?${entries.join('&')}` : '';
     }
 }
 //# sourceMappingURL=watches.js.map

package/dist/resources/watches.js.map

@@ -1 +1 @@
-{"version":3,"file":"watches.js","sourceRoot":"","sources":["../../src/resources/watches.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAkB,MAAM,kBAAkB,CAAC;AAY9D,MAAM,OAAO,OAAQ,SAAQ,YAAY;IACvC,sBAAsB;IACtB,KAAK,CAAC,MAAM,CAAC,IAAuB,EAAE,OAAwB;QAC5D,OAAO,IAAI,CAAC,KAAK,CAAQ,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAED,mCAAmC;IACnC,KAAK,CAAC,IAAI,CAAC,MAAwB,EAAE,OAAwB;QAC3D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAC1C,aAAa,EACb,MAAiC,EACjC,OAAO,CACR,CAAC;QACF,OAAO,UAAU,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CACrC,IAAI,CAAC,gBAAgB,CACnB,aAAa,EACb,EAAE,GAAG,MAAM,EAAE,MAAM,EAA6B,EAChD,OAAO,CACR,CACF,CAAC;IACJ,CAAC;IAED,wBAAwB;IACxB,KAAK,CAAC,QAAQ,CAAC,EAAU,EAAE,OAAwB;QACjD,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,IAAI,CAAQ,eAAe,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACvF,CAAC;IAED,sBAAsB;IACtB,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,IAAuB,EAAE,OAAwB;QACxE,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,MAAM,CAAQ,eAAe,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACpF,CAAC;IAED,2BAA2B;IAC3B,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,OAAwB;QAC/C,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,OAAO,CAAkB,eAAe,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,MAA0C,EAAE,OAAwB;QAC3F,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAC1C,eAAe,kBAAkB,CAAC,EAAE,CAAC,SAAS,EAC9C,MAAiC,EACjC,OAAO,CACR,CAAC;QACF,OAAO,UAAU,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CACrC,IAAI,CAAC,gBAAgB,CACnB,eAAe,kBAAkB,CAAC,EAAE,CAAC,SAAS,EAC9C,EAAE,GAAG,MAAM,EAAE,MAAM,EAA6B,EAChD,OAAO,CACR,CACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"watches.js","sourceRoot":"","sources":["../../src/resources/watches.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAkB,MAAM,kBAAkB,CAAC;AAmB9D;;;;;;;;;GASG;AACH,MAAM,OAAO,OAAQ,SAAQ,YAAY;IACvC,iFAAiF;IACjF,KAAK,CAAC,MAAM,CACV,IAAuB,EACvB,OAA6D;QAE7D,MAAM,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,KAAK,EAAE,iBAAiB;YACnC,CAAC,CAAC,cAAc,IAAI,CAAC,QAAQ,CAAC,EAAE,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,EAAE,CAAC,EAAE;YAC/E,CAAC,CAAC,aAAa,CAAC;QAClB,OAAO,IAAI,CAAC,KAAK,CAAQ,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACjD,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,IAAI,CAAC,MAAwB,EAAE,OAAwB;QAC3D,MAAM,SAAS,GAAG,KAAK,EAAE,MAAe,EAAE,EAAE,CAC1C,IAAI,CAAC,gBAAgB,CAAQ,aAAa,EAAE,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;QAC9E,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAClD,OAAO,UAAU,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,sDAAsD;IACtD,KAAK,CAAC,QAAQ,CAAC,EAAU,EAAE,OAAwB;QACjD,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,IAAI,CAAQ,eAAe,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACvF,CAAC;IAED,6CAA6C;IAC7C,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,IAAuB,EAAE,OAAwB;QACxE,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,MAAM,CAAQ,eAAe,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACpF,CAAC;IAED,+CAA+C;IAC/C,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,OAAwB;QAC/C,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,OAAO,CAAkB,eAAe,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,KAAK,CAAC,EAAU,EAAE,OAAwB;QAC9C,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,KAAK,CAAQ,eAAe,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACvF,CAAC;IAED,6BAA6B;IAC7B,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,OAAwB;QAC/C,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,KAAK,CAAQ,eAAe,kBAAkB,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACxF,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CACV,EAAU,EACV,IAAwB,EACxB,OAAwB;QAExB,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,KAAK,CAAQ,eAAe,kBAAkB,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IAChG,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CACX,IAAwB,EACxB,OAAwB;QAExB,OAAO,IAAI,CAAC,KAAK,CAAuB,qBAAqB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,IAAI,CAAC,IAAqB,EAAE,OAAwB;QACxD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAC1B,kBAAkB,EAClB,IAAI,EACJ,OAAO,CACR,CAAC;QACF,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CACf,OAAe,EACf,MAA8B,EAC9B,OAAwB;QAExB,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC7E,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CACd,eAAe,kBAAkB,CAAC,OAAO,CAAC,cAAc,EACxD,EAAE,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,EACpC,OAAO,CACR,CAAC;IACJ,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,UAAU,CACd,OAAe,EACf,MAAwB,EACxB,OAAwB;QAExB,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC1B,MAAM,SAAS,GAAG,KAAK,EAAE,MAAe,EAAE,EAAE,CAC1C,IAAI,CAAC,gBAAgB,CACnB,eAAe,kBAAkB,CAAC,OAAO,CAAC,SAAS,EACnD,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,EACrB,OAAO,CACR,CAAC;QACJ,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAClD,OAAO,UAAU,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,gEAAgE;IACxD,QAAQ,CAAC,MAA+B;QAC9C,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5C,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;gBAAE,SAAS;YAC5C,OAAO,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,CAAC;CACF"}

package/dist/resources/webhooks.d.ts

@@ -0,0 +1,57 @@
+import { BaseResource } from '../resource.js';
+import { type SignaList } from '../pagination.js';
+import type { Webhook, WebhookDelivery, DeletedResponse, WebhookCreateParams, WebhookUpdateParams, WebhookListParams, WebhookDeliveryListParams, WebhookTestResponse, WebhookRedeliveryResponse, RequestOptions } from '../types.js';
+/**
+ * Webhook endpoint management — monitoring v1 (TSK-111).
+ *
+ * Endpoints receive Standard Webhooks signed POSTs for `alert.created`
+ * and `webhook.test` events. The signing secret is
+ * returned ONCE on `create()` and `rotateSecret()` — store it before the
+ * promise resolves to nothing else, since list/retrieve responses redact it
+ * (VAL-API-009).
+ *
+ * Use `verifyWebhookSignature(headers, body, secret)` exported from the
+ * SDK root to verify deliveries on your side.
+ */
+export declare class Webhooks extends BaseResource {
+    /**
+     * Create a webhook endpoint. The response includes the plaintext
+     * signing `secret` exactly once.
+     */
+    create(body: WebhookCreateParams, options?: RequestOptions): Promise<Webhook & {
+        secret: string;
+    }>;
+    /** List webhook endpoints (secret redacted). */
+    list(params?: WebhookListParams, options?: RequestOptions): Promise<SignaList<Webhook>>;
+    /** Retrieve a webhook endpoint (secret redacted). */
+    retrieve(id: string, options?: RequestOptions): Promise<Webhook>;
+    /** Update a webhook endpoint. */
+    update(id: string, body: WebhookUpdateParams, options?: RequestOptions): Promise<Webhook>;
+    /** Soft-delete a webhook endpoint. */
+    delete(id: string, options?: RequestOptions): Promise<DeletedResponse>;
+    /**
+     * Rotate the signing secret. The new secret is returned ONCE; the previous
+     * secret remains valid for 24h so you can update your verifier without
+     * dropping deliveries (rotation overlap, VAL-WEBHOOK-005).
+     */
+    rotateSecret(id: string, options?: RequestOptions): Promise<Webhook & {
+        secret: string;
+    }>;
+    /**
+     * Send a synthetic `webhook.test` ping to the endpoint. This does NOT
+     * increment `consecutive_failures` even if the URL is unreachable
+     * (VAL-WEBHOOK-007), so admins can probe dead endpoints without
+     * triggering auto-disable.
+     */
+    test(id: string, options?: RequestOptions): Promise<WebhookTestResponse>;
+    /** List delivery audit rows for an endpoint. */
+    listDeliveries(id: string, params?: WebhookDeliveryListParams, options?: RequestOptions): Promise<SignaList<WebhookDelivery>>;
+    /** Retrieve a single delivery audit row. */
+    retrieveDelivery(id: string, deliveryId: string, options?: RequestOptions): Promise<WebhookDelivery>;
+    /**
+     * Manually redeliver a webhook event. Inserts a new attempt row referencing
+     * the same `event_id`. The dispatcher picks it up via SQS. Billable.
+     */
+    redeliver(id: string, deliveryId: string, options?: RequestOptions): Promise<WebhookRedeliveryResponse>;
+}
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/resources/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/resources/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EACV,OAAO,EACP,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EACzB,mBAAmB,EACnB,yBAAyB,EACzB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;GAWG;AACH,qBAAa,QAAS,SAAQ,YAAY;IACxC;;;OAGG;IACG,MAAM,CACV,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,OAAO,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAIxC,gDAAgD;IAC1C,IAAI,CACR,MAAM,CAAC,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAO9B,qDAAqD;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtE,iCAAiC;IAC3B,MAAM,CACV,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,OAAO,CAAC;IAKnB,sCAAsC;IAChC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAK5E;;;;OAIG;IACG,YAAY,CAChB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,OAAO,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IASxC;;;;;OAKG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAS9E,gDAAgD;IAC1C,cAAc,CAClB,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,yBAAyB,EAClC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;IAYtC,4CAA4C;IACtC,gBAAgB,CACpB,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,eAAe,CAAC;IAU3B;;;OAGG;IACG,SAAS,CACb,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,yBAAyB,CAAC;CAStC"}

package/dist/resources/webhooks.js

@@ -0,0 +1,86 @@
+import { BaseResource } from '../resource.js';
+import { createList } from '../pagination.js';
+/**
+ * Webhook endpoint management — monitoring v1 (TSK-111).
+ *
+ * Endpoints receive Standard Webhooks signed POSTs for `alert.created`
+ * and `webhook.test` events. The signing secret is
+ * returned ONCE on `create()` and `rotateSecret()` — store it before the
+ * promise resolves to nothing else, since list/retrieve responses redact it
+ * (VAL-API-009).
+ *
+ * Use `verifyWebhookSignature(headers, body, secret)` exported from the
+ * SDK root to verify deliveries on your side.
+ */
+export class Webhooks extends BaseResource {
+    /**
+     * Create a webhook endpoint. The response includes the plaintext
+     * signing `secret` exactly once.
+     */
+    async create(body, options) {
+        return this._post('/v1/webhooks', body, options);
+    }
+    /** List webhook endpoints (secret redacted). */
+    async list(params, options) {
+        const fetchPage = async (cursor) => this._getListResponse('/v1/webhooks', { ...params, cursor }, options);
+        const firstPage = await fetchPage(params?.cursor);
+        return createList(firstPage, fetchPage);
+    }
+    /** Retrieve a webhook endpoint (secret redacted). */
+    async retrieve(id, options) {
+        this._validateId(id);
+        return this._get(`/v1/webhooks/${encodeURIComponent(id)}`, undefined, options);
+    }
+    /** Update a webhook endpoint. */
+    async update(id, body, options) {
+        this._validateId(id);
+        return this._patch(`/v1/webhooks/${encodeURIComponent(id)}`, body, options);
+    }
+    /** Soft-delete a webhook endpoint. */
+    async delete(id, options) {
+        this._validateId(id);
+        return this._delete(`/v1/webhooks/${encodeURIComponent(id)}`, options);
+    }
+    /**
+     * Rotate the signing secret. The new secret is returned ONCE; the previous
+     * secret remains valid for 24h so you can update your verifier without
+     * dropping deliveries (rotation overlap, VAL-WEBHOOK-005).
+     */
+    async rotateSecret(id, options) {
+        this._validateId(id);
+        return this._post(`/v1/webhooks/${encodeURIComponent(id)}/rotate-secret`, {}, options);
+    }
+    /**
+     * Send a synthetic `webhook.test` ping to the endpoint. This does NOT
+     * increment `consecutive_failures` even if the URL is unreachable
+     * (VAL-WEBHOOK-007), so admins can probe dead endpoints without
+     * triggering auto-disable.
+     */
+    async test(id, options) {
+        this._validateId(id);
+        return this._post(`/v1/webhooks/${encodeURIComponent(id)}/test`, {}, options);
+    }
+    /** List delivery audit rows for an endpoint. */
+    async listDeliveries(id, params, options) {
+        this._validateId(id);
+        const fetchPage = async (cursor) => this._getListResponse(`/v1/webhooks/${encodeURIComponent(id)}/deliveries`, { ...params, cursor }, options);
+        const firstPage = await fetchPage(params?.cursor);
+        return createList(firstPage, fetchPage);
+    }
+    /** Retrieve a single delivery audit row. */
+    async retrieveDelivery(id, deliveryId, options) {
+        this._validateId(id);
+        this._validateId(deliveryId, 'deliveryId');
+        return this._get(`/v1/webhooks/${encodeURIComponent(id)}/deliveries/${encodeURIComponent(deliveryId)}`, undefined, options);
+    }
+    /**
+     * Manually redeliver a webhook event. Inserts a new attempt row referencing
+     * the same `event_id`. The dispatcher picks it up via SQS. Billable.
+     */
+    async redeliver(id, deliveryId, options) {
+        this._validateId(id);
+        this._validateId(deliveryId, 'deliveryId');
+        return this._post(`/v1/webhooks/${encodeURIComponent(id)}/deliveries/${encodeURIComponent(deliveryId)}/redeliver`, {}, options);
+    }
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/resources/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/resources/webhooks.ts"],"names":[],"mappings":"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"}