@signa-so/sdk 0.16.0 → 0.21.0

package/README.md

@@ -19,11 +19,14 @@ const signa = new Signa({ api_key: 'sig_xxx' });
 const tm = await signa.trademarks.retrieve('tm_abc123');
 
 // Search trademarks (POST with structured filters)
-const results = await signa.trademarks.search({ query: 'nike', filters: { offices: ['US'] } });
+const results = await signa.trademarks.search({ q: 'nike', filters: { offices: ['US'] } });
 
 // Text search via GET
 const searched = await signa.trademarks.list({ q: 'nike', offices: 'US' });
 
+// Exact marks, excluding one owner (lists go on the wire as repeated keys)
+const variants = await signa.trademarks.list({ mark_text_is: ['nike', 'nikey'], owner_id_not: ['own_xxx'] });
+
 // List with auto-pagination
 const page = await signa.trademarks.list({ limit: 50 });
 for (const tm of page.data) {
@@ -61,7 +64,7 @@ await signa.trademarks.events('tm_xxx');
 
 ```ts
 await signa.owners.retrieve('own_xxx');
-await signa.owners.list({ query: 'Nike', country: 'US' });
+await signa.owners.list({ q: 'Nike', country_code: 'US' });
 await signa.owners.trademarks('own_xxx');
 ```
 
@@ -69,7 +72,7 @@ await signa.owners.trademarks('own_xxx');
 
 ```ts
 await signa.attorneys.retrieve('att_xxx');
-await signa.attorneys.list({ query: 'Smith' });
+await signa.attorneys.list({ q: 'Smith' });
 await signa.attorneys.trademarks('att_xxx');
 ```
 
@@ -77,7 +80,7 @@ await signa.attorneys.trademarks('att_xxx');
 
 ```ts
 await signa.firms.retrieve('firm_xxx');
-await signa.firms.list({ query: 'Baker McKenzie' });
+await signa.firms.list({ q: 'Baker McKenzie' });
 await signa.firms.attorneys('firm_xxx');
 await signa.firms.trademarks('firm_xxx');
 ```
@@ -91,19 +94,26 @@ await signa.proceedings.list({ trademark_id: 'tm_xxx' });
 
 ### `signa.trademarks.search()` (POST)
 
-For complex queries with structured filters, aggregations, and strategies:
+For structured filters, `mark_text` operators, exclusions and aggregations.
+`q` ranks through the `similarity` channels; `Presets.knockout` and
+`Presets.clearance` spread into any search request:
 
 ```ts
+import Signa, { Presets } from '@signa-so/sdk';
+
 await signa.trademarks.search({
-  query: 'nike',
-  strategies: ['exact', 'phonetic'],
-  filters: { offices: ['US'], status_primary: 'active', nice_classes: [25, 35] },
+  q: 'nike',
+  ...Presets.clearance,
+  filters: { offices: ['US'], status_primary: 'active', nice_classes: [25, 35], mark_text: { starts_with: ['ni'] } },
+  exclude: { owner_id: ['own_xxx'] },
   options: { aggregations: ['status_stage', 'office_code'], include_total: true },
-  sort: '-filing_date',
   limit: 20,
 });
 ```
 
+Upgrading from 0.16 or earlier: see the 0.17.0 migration table in
+[CHANGELOG.md](./CHANGELOG.md).
+
 ### `signa.references`
 
 ```ts

package/dist/_internals/query-string.d.ts

@@ -1,11 +1,25 @@
+/** The six trademark search text operators (`mark_text_<op>`, `mark_text_not_<op>`). */
+export declare const MARK_TEXT_OPERATORS: readonly ["is", "word", "starts_with", "ends_with", "contains", "pattern"];
+/** The id exclusions (`<key>_not` on GET, `exclude.<key>` on POST). */
+export declare const ID_EXCLUSION_KEYS: readonly ["entity_id", "entity_group", "owner_id", "trademark_ids"];
+/**
+ * GET list params sent as repeated keys (`mark_text_is=a&mark_text_is=b`),
+ * never comma-joined: commas are legal inside marks, and the API does not
+ * split these keys on commas.
+ */
+export declare const REPEATED_LIST_KEYS: ReadonlySet<string>;
 /**
  * Build a URL query string from a params object.
  *
  * Conventions (see `.signa/docs/decisions/query-parameter-conventions.md`):
  * - Arrays serialize as comma-separated: `?offices=US,EM`
+ * - Keys in `repeatedKeys` (default {@link REPEATED_LIST_KEYS}) serialize as
+ *   repeated keys instead: `?mark_text_is=a&mark_text_is=b`
  * - Date ranges live on flat underscore keys: `?filing_date_gte=2020-01-01`
- * - Undefined/null values are omitted
+ * - Undefined/null values and empty arrays are omitted
  * - Numbers and booleans are stringified
  */
-export declare function buildQueryString(params: Record<string, unknown>): string;
+export declare function buildQueryString(params: Record<string, unknown>, { repeatedKeys }?: {
+    repeatedKeys?: ReadonlySet<string>;
+}): string;
 //# sourceMappingURL=query-string.d.ts.map

package/dist/_internals/query-string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-string.d.ts","sourceRoot":"","sources":["../../src/_internals/query-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAkBxE"}
+{"version":3,"file":"query-string.d.ts","sourceRoot":"","sources":["../../src/_internals/query-string.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,4EAA6E,CAAC;AAE9G,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,qEAAsE,CAAC;AAErG;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAIjD,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,EAAE,YAAiC,EAAE,GAAE;IAAE,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAO,GACjF,MAAM,CAkBR"}

package/dist/_internals/query-string.js

@@ -1,24 +1,44 @@
+/** The six trademark search text operators (`mark_text_<op>`, `mark_text_not_<op>`). */
+export const MARK_TEXT_OPERATORS = ['is', 'word', 'starts_with', 'ends_with', 'contains', 'pattern'];
+/** The id exclusions (`<key>_not` on GET, `exclude.<key>` on POST). */
+export const ID_EXCLUSION_KEYS = ['entity_id', 'entity_group', 'owner_id', 'trademark_ids'];
+/**
+ * GET list params sent as repeated keys (`mark_text_is=a&mark_text_is=b`),
+ * never comma-joined: commas are legal inside marks, and the API does not
+ * split these keys on commas.
+ */
+export const REPEATED_LIST_KEYS = new Set([
+    ...MARK_TEXT_OPERATORS.map((op) => `mark_text_${op}`),
+    ...MARK_TEXT_OPERATORS.map((op) => `mark_text_not_${op}`),
+    ...ID_EXCLUSION_KEYS.map((key) => `${key}_not`),
+]);
 /**
  * Build a URL query string from a params object.
  *
  * Conventions (see `.signa/docs/decisions/query-parameter-conventions.md`):
  * - Arrays serialize as comma-separated: `?offices=US,EM`
+ * - Keys in `repeatedKeys` (default {@link REPEATED_LIST_KEYS}) serialize as
+ *   repeated keys instead: `?mark_text_is=a&mark_text_is=b`
  * - Date ranges live on flat underscore keys: `?filing_date_gte=2020-01-01`
- * - Undefined/null values are omitted
+ * - Undefined/null values and empty arrays are omitted
  * - Numbers and booleans are stringified
  */
-export function buildQueryString(params) {
+export function buildQueryString(params, { repeatedKeys = REPEATED_LIST_KEYS } = {}) {
     const parts = [];
+    const pair = (key, value) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`;
     for (const [key, value] of Object.entries(params)) {
         if (value === undefined || value === null)
             continue;
         if (Array.isArray(value)) {
-            if (value.length > 0) {
-                parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(value.map(String).join(','))}`);
-            }
+            if (value.length === 0)
+                continue;
+            if (repeatedKeys.has(key))
+                parts.push(...value.map((item) => pair(key, item)));
+            else
+                parts.push(pair(key, value.map(String).join(',')));
         }
         else {
-            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+            parts.push(pair(key, value));
         }
     }
     return parts.length > 0 ? `?${parts.join('&')}` : '';

package/dist/_internals/query-string.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-string.js","sourceRoot":"","sources":["../../src/_internals/query-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA+B;IAC9D,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAEpD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,KAAK,CAAC,IAAI,CACR,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAChF,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACvD,CAAC"}
+{"version":3,"file":"query-string.js","sourceRoot":"","sources":["../../src/_internals/query-string.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,CAAU,CAAC;AAE9G,uEAAuE;AACvE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,CAAU,CAAC;AAErG;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC;IAC7D,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC;IACrD,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,iBAAiB,EAAE,EAAE,CAAC;IACzD,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC;CAChD,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA+B,EAC/B,EAAE,YAAY,GAAG,kBAAkB,KAA6C,EAAE;IAElF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,KAAc,EAAE,EAAE,CAC3C,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;IAEpE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAEpD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YACjC,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;;gBAC1E,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC1D,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACvD,CAAC"}