@signa-so/sdk 0.2.2 → 0.7.0

package/dist/resources/screening.js

@@ -0,0 +1,66 @@
+import { BaseResource } from '../resource.js';
+/**
+ * Screening operations — PUBLIC beta (requires the `screening:read` scope,
+ * granted to design partners during beta).
+ *
+ * Public exposure of the single-name screening surface was authorized by the
+ * founder's 2026-07-10 public-beta decision. `checkListing` is the listing-check
+ * surface (ENG-30): extract candidate marks from commerce text and fan them out
+ * through the screening core.
+ */
+export class Screening extends BaseResource {
+    /**
+     * Screen a single candidate name — `GET /v1/screening`.
+     *
+     * PUBLIC beta. Requires the `screening:read` scope, granted to design partners
+     * during beta. Returns coarse risk bands and a verdict, never a numeric score.
+     * Billed at 10 units per request. Not legal advice.
+     *
+     * ```typescript
+     * const result = await signa.screening.screen({
+     *   q: 'KOFEE',
+     *   nice_classes: [30, 43],
+     *   jurisdictions: ['US', 'EU'],
+     * });
+     * // result.screening.verdict → 'clear' | 'caution' | 'needs_review' | 'high_risk'
+     * ```
+     * `needs_review` is a would-be `clear` the screen could not complete to `clear`
+     * standard, most often incomplete register coverage for a requested territory
+     * but also a stale corpus, capped horizon, failed lane, unsupported language,
+     * or low-confidence class inference. Inspect `result.screening.coverage` for the
+     * details when present (it can be absent if the coverage assessment failed).
+     * Pass `trademark_id` instead of `q` to screen an existing register record;
+     * its own collapsed family is excluded from the returned conflicts.
+     */
+    async screen(params, options) {
+        return this._get('/v1/screening', { ...params }, options);
+    }
+    /**
+     * Screen a whole LISTING — `POST /v1/screening/listings`.
+     *
+     * Deterministic + synchronous. Extracts candidate marks from `title` / `brand`
+     * / `description` / `keywords`, fans them out through the screening core, and
+     * returns a listing-level verdict with per-candidate conflicts. Billed flat at
+     * 25 units per listing regardless of internal fan-out. Not legal advice.
+     * Beta limitation: common-word listings are over-flagged, so treat `caution`
+     * as no-signal pending the ENG-199 verdict-separation redesign.
+     * Supply `nice_classes` whenever possible: caller-provided classes are the only
+     * high-quality class signal that may corroborate a conflict upward. If your
+     * platform has only a category label, derive them explicitly with
+     * `categoryToNiceClasses(category)` from `@signa-so/sdk`.
+     *
+     * ```typescript
+     * import { categoryToNiceClasses } from '@signa-so/sdk';
+     *
+     * const result = await signa.screening.checkListing({
+     *   title: 'Vintage AirPods Case — Handmade Leather',
+     *   nice_classes: categoryToNiceClasses('handbags'),
+     * });
+     * // result.listing.verdict → 'clear' | 'caution' | 'high_risk'
+     * ```
+     */
+    async checkListing(params, options) {
+        return this._post('/v1/screening/listings', params, options);
+    }
+}
+//# sourceMappingURL=screening.js.map

package/dist/resources/screening.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screening.js","sourceRoot":"","sources":["../../src/resources/screening.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAS9C;;;;;;;;GAQG;AACH,MAAM,OAAO,SAAU,SAAQ,YAAY;IACzC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,MAAM,CAAC,MAAoB,EAAE,OAAwB;QACzD,OAAO,IAAI,CAAC,IAAI,CAAe,eAAe,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,YAAY,CAChB,MAA0B,EAC1B,OAAwB;QAExB,OAAO,IAAI,CAAC,KAAK,CAAqB,wBAAwB,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACnF,CAAC;CACF"}

package/dist/resources/suggest.d.ts

@@ -0,0 +1,16 @@
+import { BaseResource } from '../resource.js';
+import { type SignaList } from '../pagination.js';
+import type { CrossEntitySuggestion, CrossEntitySuggestParams, RequestOptions } from '../types.js';
+export declare class Suggest extends BaseResource {
+    /**
+     * Cross-entity typeahead across trademarks, owners, attorneys, and firms.
+     *
+     * Scope: `trademarks:read`.
+     *
+     * ```typescript
+     * const suggestions = await signa.suggest.crossEntity({ q: 'apple' });
+     * ```
+     */
+    crossEntity(params: CrossEntitySuggestParams, options?: RequestOptions): Promise<SignaList<CrossEntitySuggestion>>;
+}
+//# sourceMappingURL=suggest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../src/resources/suggest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EACV,qBAAqB,EACrB,wBAAwB,EACxB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,qBAAa,OAAQ,SAAQ,YAAY;IACvC;;;;;;;;OAQG;IACG,WAAW,CACf,MAAM,EAAE,wBAAwB,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;CAU7C"}

package/dist/resources/suggest.js

@@ -0,0 +1,18 @@
+import { BaseResource } from '../resource.js';
+import { createList } from '../pagination.js';
+export class Suggest extends BaseResource {
+    /**
+     * Cross-entity typeahead across trademarks, owners, attorneys, and firms.
+     *
+     * Scope: `trademarks:read`.
+     *
+     * ```typescript
+     * const suggestions = await signa.suggest.crossEntity({ q: 'apple' });
+     * ```
+     */
+    async crossEntity(params, options) {
+        const response = await this._getListResponse('/v1/suggest', params, options);
+        return createList({ ...response, has_more: false }, () => Promise.resolve({ ...response, data: [], has_more: false }));
+    }
+}
+//# sourceMappingURL=suggest.js.map

package/dist/resources/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../../src/resources/suggest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAkB,MAAM,kBAAkB,CAAC;AAO9D,MAAM,OAAO,OAAQ,SAAQ,YAAY;IACvC;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CACf,MAAgC,EAChC,OAAwB;QAExB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAC1C,aAAa,EACb,MAA4C,EAC5C,OAAO,CACR,CAAC;QACF,OAAO,UAAU,CAAC,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CACvD,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAC5D,CAAC;IACJ,CAAC;CACF"}

package/dist/resources/trademarks.d.ts

@@ -1,29 +1,100 @@
 import { BaseResource } from '../resource.js';
 import { type SignaList } from '../pagination.js';
-import type { Trademark, TrademarkSummary, Event, TrademarkRetrieveParams, TrademarkListParams, TrademarkHistoryParams, TrademarkBatchBody, TrademarkBatchResponse, TrademarkChangesParams, TrademarkChange, TrademarkRelatedParams, TrademarkRelationship, TrademarkCoverageParams, TrademarkCoverage, TrademarkProceedingsParams, TrademarkProceeding, TrademarkSource, TrademarkSuggestParams, TrademarkSuggestion, RequestOptions } from '../types.js';
+import type { Trademark, TrademarkSummary, TrademarkSearchResult, Event, TrademarkRetrieveParams, TrademarkListParams, TrademarkSearchBody, TrademarkHistoryParams, TrademarkBatchBody, TrademarkBatchResponse, TrademarkChangesParams, TrademarkChange, TrademarkRelatedParams, TrademarkRelationship, TrademarkCoverageParams, TrademarkCoverage, TrademarkProceedingsParams, TrademarkProceeding, TrademarkAssignmentsParams, TrademarkAssignment, TrademarkDocumentParams, TrademarkDocument, TrademarkSource, TrademarkSuggestParams, TrademarkSuggestion, TrademarkImageSearchParams, ImageSearchResults, RequestOptions } from '../types.js';
+type TrademarkWithOwners = {
+    owners?: Array<{
+        name?: string | null;
+    }> | null;
+};
+export declare function primaryOwnerName(trademark: TrademarkWithOwners): string | null;
 export declare 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: ['office_extensions']` to add the raw office-specific
+     * extension blob (omitted by default). Pass `language` to prefer matching
+     * goods/services classification variants without filtering unmatched groups.
+     *
      * ```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: ['office_extensions'] });
+     * const tm = await signa.trademarks.retrieve('tm_abc123', { language: 'en' });
      * ```
      */
     retrieve(id: string, params?: TrademarkRetrieveParams, options?: RequestOptions): Promise<Trademark>;
     /**
-     * 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'] });
      *
-     * for await (const tm of signa.trademarks.list({ jurisdiction_code: 'US' })) {
+     * // Explicit sort
+     * const sorted = await signa.trademarks.list({ offices: ['US'], sort: '-registration_date' });
+     *
+     * // Auto-pagination
+     * for await (const tm of signa.trademarks.list({ jurisdictions: ['US'] })) {
      *   console.log(tm.mark_text);
      * }
      * ```
      */
     list(params?: TrademarkListParams, options?: RequestOptions): Promise<SignaList<TrademarkSummary>>;
+    /**
+     * 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: ['US'], status_primary: 'active' },
+     *   sort: '-filing_date',
+     *   options: { include_total: true },
+     * });
+     * ```
+     */
+    search(params: TrademarkSearchBody, options?: RequestOptions): Promise<SignaList<TrademarkSearchResult>>;
+    /**
+     * Search trademarks by logo/image similarity (beta, internal). Requires the
+     * `image-search:read` scope. Provide EXACTLY ONE image source:
+     *   - `image`: raw bytes (multipart upload — Blob / ArrayBuffer / Uint8Array)
+     *   - `image_url`: an https URL (fetched + SSRF-guarded server-side)
+     *   - `media_id`: an existing mark's media id (reuses its stored vector)
+     *
+     * Returns mark-level hits, each with the §3.5 signal channels + a
+     * `thumbnail_url`. Results are a bounded top-K (limit ≤ 100, not paginable).
+     *
+     * ```typescript
+     * const bytes = await fs.readFile('logo.png');
+     * const res = await signa.trademarks.searchByImage({
+     *   image: bytes,
+     *   filters: { offices: ['US'], nice_classes: [9] },
+     *   channels: ['visual', 'exact_dup'],
+     * });
+     * for (const hit of res.data) console.log(hit.trademark.mark_text, hit.band);
+     * ```
+     */
+    searchByImage(params: TrademarkImageSearchParams, options?: RequestOptions): Promise<ImageSearchResults>;
     /**
      * List event history for a trademark.
      *
@@ -39,7 +110,7 @@ export declare class Trademarks extends BaseResource {
      * ```typescript
      * const result = await signa.trademarks.batch({ ids: ['tm_abc', 'tm_def'] });
      * const result = await signa.trademarks.batch({
-     *   identifiers: [{ application_number: '97123456', office: 'uspto' }],
+     *   identifiers: [{ application_number: '97123456', office: 'US' }],
      * });
      * ```
      */
@@ -74,7 +145,12 @@ export declare class Trademarks extends BaseResource {
     coverage(id: string, params?: TrademarkCoverageParams, options?: RequestOptions): Promise<SignaList<TrademarkCoverage>>;
     /** Proceedings (oppositions, cancellations) linked to a trademark. */
     proceedings(id: string, params?: TrademarkProceedingsParams, options?: RequestOptions): Promise<SignaList<TrademarkProceeding>>;
+    /** Recorded assignment chain of title linked to a trademark. */
+    assignments(id: string, params?: TrademarkAssignmentsParams, options?: RequestOptions): Promise<SignaList<TrademarkAssignment>>;
+    /** Office documents linked to a trademark. */
+    documents(id: string, params?: TrademarkDocumentParams, options?: RequestOptions): Promise<SignaList<TrademarkDocument>>;
     /** Get the redirect URL for a trademark media asset (image, sound, etc). */
     media(id: string, mediaId: string, options?: RequestOptions): Promise<string>;
 }
+export {};
 //# sourceMappingURL=trademarks.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"trademarks.d.ts","sourceRoot":"","sources":["../../src/resources/trademarks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,KAAK,EACL,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,0BAA0B,EAC1B,mBAAmB,EACnB,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,qBAAa,UAAW,SAAQ,YAAY;IAC1C;;;;;;;OAOG;IACG,QAAQ,CACZ,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,uBAAuB,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC;IAQrB;;;;;;;;;;;OAWG;IACG,IAAI,CACR,MAAM,CAAC,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAQvC;;;;;;;OAOG;IACG,OAAO,CACX,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAa5B;;;;;;;;;OASG;IACG,KAAK,CACT,IAAI,EAAE,kBAAkB,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,sBAAsB,CAAC;IAIlC;;;;;;OAMG;IACG,OAAO,CACX,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;IAgBtC;;;;;;OAMG;IACG,OAAO,CACX,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;IAgB5C;;;;;;OAMG;IACG,OAAO,CACX,MAAM,EAAE,sBAAsB,EAC9B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAW1C,kDAAkD;IAC5C,MAAM,CACV,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,eAAe,CAAC;IAS3B,oEAAoE;IAC9D,QAAQ,CACZ,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,uBAAuB,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAgBxC,sEAAsE;IAChE,WAAW,CACf,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,0BAA0B,EACnC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAgB1C,4EAA4E;IACtE,KAAK,CACT,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,MAAM,CAAC;CAQnB"}
+{"version":3,"file":"trademarks.d.ts","sourceRoot":"","sources":["../../src/resources/trademarks.ts"],"names":[],"mappings":"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"}

package/dist/resources/trademarks.js

@@ -1,12 +1,22 @@
 import { BaseResource } from '../resource.js';
 import { createList } from '../pagination.js';
+export function primaryOwnerName(trademark) {
+    return trademark.owners?.[0]?.name ?? null;
+}
 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: ['office_extensions']` to add the raw office-specific
+     * extension blob (omitted by default). Pass `language` to prefer matching
+     * goods/services classification variants without filtering unmatched groups.
+     *
      * ```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: ['office_extensions'] });
+     * const tm = await signa.trademarks.retrieve('tm_abc123', { language: 'en' });
      * ```
      */
     async retrieve(id, params, options) {
@@ -14,16 +24,28 @@ export class Trademarks extends BaseResource {
         return this._get(`/v1/trademarks/${encodeURIComponent(id)}`, {
             include: params?.include,
             fields: params?.fields,
+            language: params?.language,
         }, 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'] });
      *
-     * for await (const tm of signa.trademarks.list({ jurisdiction_code: 'US' })) {
+     * // Explicit sort
+     * const sorted = await signa.trademarks.list({ offices: ['US'], sort: '-registration_date' });
+     *
+     * // Auto-pagination
+     * for await (const tm of signa.trademarks.list({ jurisdictions: ['US'] })) {
      *   console.log(tm.mark_text);
      * }
      * ```
@@ -35,6 +57,99 @@ 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: ['US'], 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);
+        });
+    }
+    /**
+     * Search trademarks by logo/image similarity (beta, internal). Requires the
+     * `image-search:read` scope. Provide EXACTLY ONE image source:
+     *   - `image`: raw bytes (multipart upload — Blob / ArrayBuffer / Uint8Array)
+     *   - `image_url`: an https URL (fetched + SSRF-guarded server-side)
+     *   - `media_id`: an existing mark's media id (reuses its stored vector)
+     *
+     * Returns mark-level hits, each with the §3.5 signal channels + a
+     * `thumbnail_url`. Results are a bounded top-K (limit ≤ 100, not paginable).
+     *
+     * ```typescript
+     * const bytes = await fs.readFile('logo.png');
+     * const res = await signa.trademarks.searchByImage({
+     *   image: bytes,
+     *   filters: { offices: ['US'], nice_classes: [9] },
+     *   channels: ['visual', 'exact_dup'],
+     * });
+     * for (const hit of res.data) console.log(hit.trademark.mark_text, hit.band);
+     * ```
+     */
+    async searchByImage(params, options) {
+        const { image, image_filename, image_url, media_id, filters, territory_match, crop, limit, channels } = params;
+        if (image !== undefined) {
+            // Multipart upload — the file part plus JSON-encoded scalars/objects.
+            const form = new FormData();
+            const blob = image instanceof Blob
+                ? image
+                : new Blob([(image instanceof Uint8Array ? image : new Uint8Array(image)).slice()]);
+            form.append('image', blob, image_filename ?? 'image');
+            if (filters !== undefined)
+                form.append('filters', JSON.stringify(filters));
+            // territory_match is a plain enum string on the multipart transport (not JSON-encoded).
+            if (territory_match !== undefined)
+                form.append('territory_match', territory_match);
+            if (crop !== undefined)
+                form.append('crop', JSON.stringify(crop));
+            if (channels !== undefined)
+                form.append('channels', JSON.stringify(channels));
+            if (limit !== undefined)
+                form.append('limit', String(limit));
+            return this._post('/v1/trademarks/search/image', form, options);
+        }
+        // JSON body — image_url or media_id.
+        const body = {};
+        if (image_url !== undefined)
+            body.image_url = image_url;
+        if (media_id !== undefined)
+            body.media_id = media_id;
+        if (filters !== undefined)
+            body.filters = filters;
+        if (territory_match !== undefined)
+            body.territory_match = territory_match;
+        if (crop !== undefined)
+            body.crop = crop;
+        if (channels !== undefined)
+            body.channels = channels;
+        if (limit !== undefined)
+            body.limit = limit;
+        return this._post('/v1/trademarks/search/image', body, options);
+    }
     /**
      * List event history for a trademark.
      *
@@ -57,7 +172,7 @@ export class Trademarks extends BaseResource {
      * ```typescript
      * const result = await signa.trademarks.batch({ ids: ['tm_abc', 'tm_def'] });
      * const result = await signa.trademarks.batch({
-     *   identifiers: [{ application_number: '97123456', office: 'uspto' }],
+     *   identifiers: [{ application_number: '97123456', office: 'US' }],
      * });
      * ```
      */
@@ -116,6 +231,18 @@ export class Trademarks extends BaseResource {
         const response = await this._getListResponse(`/v1/trademarks/${encodeURIComponent(id)}/proceedings`, params, options);
         return createList(response, (cursor) => this._getListResponse(`/v1/trademarks/${encodeURIComponent(id)}/proceedings`, { ...params, cursor }, options));
     }
+    /** Recorded assignment chain of title linked to a trademark. */
+    async assignments(id, params, options) {
+        this._validateId(id);
+        const response = await this._getListResponse(`/v1/trademarks/${encodeURIComponent(id)}/assignments`, params, options);
+        return createList(response, (cursor) => this._getListResponse(`/v1/trademarks/${encodeURIComponent(id)}/assignments`, { ...params, cursor }, options));
+    }
+    /** Office documents linked to a trademark. */
+    async documents(id, params, options) {
+        this._validateId(id);
+        const response = await this._getListResponse(`/v1/trademarks/${encodeURIComponent(id)}/documents`, params, options);
+        return createList(response, (cursor) => this._getListResponse(`/v1/trademarks/${encodeURIComponent(id)}/documents`, { ...params, cursor }, options));
+    }
     /** Get the redirect URL for a trademark media asset (image, sound, etc). */
     async media(id, mediaId, options) {
         this._validateId(id, 'id');

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,77 @@
 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, WatchAttestation, WatchAttestationParams, 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
+ * `min_match_tier` 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>;
+    /**
+     * Fetch the monthly proof-of-monitoring attestation (JSON) for a closed UTC
+     * calendar month. Defaults to the previous month. The current (open) month
+     * returns 422 unless `{ partial: true }`. Deterministic: re-fetch a closed
+     * period later and compare `content_hash` to verify integrity.
+     *
+     * The PDF business record is available at the HTTP layer via
+     * `GET /v1/watches/{id}/attestation?format=pdf` (or `Accept: application/pdf`).
+     *
+     * Required scope: `portfolios:manage`. Cross-org / unknown watch returns 404.
+     */
+    attestation(watchId: string, params?: WatchAttestationParams, options?: RequestOptions): Promise<WatchAttestation>;
+    /** 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,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;;;;;;;;;;OAUG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,sBAAsB,EAC/B,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"}