api/openapi.cloud.yaml (3)

12181-12185: Clarify matching semantics and add examples/constraints to the parameter doc.

Great that the doc now reflects the case-insensitive partial match. To reduce ambiguity and improve client UX, consider documenting what “partial” means with a short example and add basic constraints to prevent pathological queries.

Proposed edit:

-      description: |-
-        Filter customers by key.
-        Case-insensitive partial match.
+      description: |-
+        Filter customers by key.
+        Case-insensitive substring match (e.g., `?key=acme` matches `acme-inc`, `AcMe_2`).
+        Matching is performed against the entire key value.
       schema:
         type: string
+        minLength: 2
+        maxLength: 128
       explode: false
+      example: acme

---

12182-12182: Call out Unicode and normalization expectations (one sentence).

If the backend uses case folding (e.g., LOWER/ILIKE or equivalent), specifying that matching is Unicode-aware (or ASCII-only) removes guesswork for clients using non-ASCII keys.

Suggested wording to append to the description:

• “Case-insensitive comparison is Unicode-aware and locale-independent.” (If true)
• Or: “Case-insensitive comparison is ASCII-only.” (If true)

Please select the accurate statement based on the implementation.

---

12181-12184: Plan for performance: substring searches need indexing and guardrails.

Substring matches (%term%) can degrade query performance on large datasets without proper indexing. If the backend uses Postgres, consider a trigram index on the key (e.g., GIN with gin_trgm_ops) and/or a functional index on lower(key). The proposed minLength helps reduce extremely short terms.

api/spec/src/customer/customer.tsp (2)

122-127: Doc change LGTM; consider adding example and clarifying “exact match” path to avoid ambiguity

The “Case-insensitive partial match” update aligns with the backend change. To help users and SDKs, add an example and explicitly point to the exact-match alternative.

Apply this diff:

   /**
    * Filter customers by key.
-   * Case-insensitive partial match.
+   * Case-insensitive partial (substring) match.
+   * For exact key lookup, use GET /api/v1/customers/{customerIdOrKey}.
   */
   @query
+  @example("acme")
   key?: string;

---

43-53: Clarify case-sensitivity for GET by key

Since list uses case-insensitive partial matching, explicitly documenting that “Get customer by ID or key” performs an exact key match will prevent confusion.

Suggestion: Add a sentence to the operation summary/description like “When using a key, matching is exact (not partial).”

openmeter/customer/adapter/customer.go (2)

49-56: Consider query performance: case-insensitive substring filters need indexes

ContainsFold typically compiles to LOWER(key) LIKE '%' || LOWER($1) || '%', which can’t use standard btree indexes. On larger tables this becomes expensive, especially when filters are broad.

Options:

• Add trigram index (Postgres): CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_customer_key_trgm ON customer USING gin (key gin_trgm_ops);
• If you standardize on case-insensitive equality elsewhere, consider citext for equality predicates; for substring, keep trigram.
• If applicable, reject too-short patterns (e.g., < 2 chars) in ListCustomersInput.Validate() to reduce unselective scans.

---

49-72: Add tests to lock in new semantics and the empty-string behavior

Given the change in semantics, add tests that assert:

• key filter is case-insensitive and substring-based,
• empty/whitespace key is ignored (no filter applied).

I can draft table-driven tests for ListCustomers covering positive, negative, and empty-string cases. Want me to open a follow-up PR with tests?

api/openapi.yaml (3)

12178-12183: Clarify semantics and add examples for substring search.

“Case-insensitive partial match.” is terse and can be misread. Recommend making it explicit that this is a substring match and that passing the full key may still return multiple rows. Also document empty-string behavior.

Apply this diff to improve the description and add parameter-level examples:

       description: |-
         Filter customers by key.
-        Case-insensitive partial match.
+        Case-insensitive substring match.
+        Matches any customer keys containing the provided value, regardless of case.
+        Examples:
+          - ?key=acme → matches "ACME-001", "myAcmeCompany"
+          - ?key=001 → matches "acme-001", "cust-001"
+        Note: Providing the full key may still return multiple results if other keys contain it as a substring.
       schema:
         type: string
+        minLength: 1
       explode: false

If the backend treats key="" as “match all”, consider stating that explicitly instead of enforcing minLength: 1.

---

12181-12183: Consider removing explode: false for a plain string param.

For a string with style=form (default), explode is irrelevant; keeping it is harmless but redundant.

Apply this diff if you prefer to reduce noise:

       schema:
         type: string
-      explode: false

---

12178-12183: Add a release-note snippet describing the changed matching semantics.

Even without signature changes, clients depending on exact match semantics may see broader result sets. Surface this explicitly in release notes with upgrade guidance.

I can draft a concise release-note block and an SDK changelog entry if you confirm the desired behavior for empty strings and trimming rules (e.g., whitespace, Unicode normalization).

api/client/javascript/src/zod/index.ts (2)

6741-6744: Normalize and ignore empty/whitespace-only values to avoid accidental “match-all” queries

With partial matching, passing an empty string ("") would likely match everything. Consider trimming and converting blank inputs to undefined so that an empty value behaves the same as omitting the filter.

Apply this diff within the current chain:

   key: zod.coerce
     .string()
+    .transform((s) => s.trim() || undefined)
     .optional()
-    .describe('Filter customers by key.\nCase-insensitive partial match.'),
+    .describe('Filter customers by key.\nCase-insensitive partial match (substring).\nEmpty/whitespace-only values are ignored.'),

---

6741-6744: Optional: guard against multi-valued query params being coerced to a comma-joined string

zod.coerce.string() will stringify arrays (e.g., ['ac','me'] -> 'ac,me'), which could unintentionally broaden the search. If your query builder allows repeated params (e.g., ?key=a&key=b), consider taking only the first element.

If desired, switch to a preprocess step before coercion (requires adjusting the surrounding code slightly):

// Example helper (outside this diff range)
const firstString = <T>(v: T) =>
  Array.isArray(v) ? v[0] : v;

// Replace chain with:
key: zod.preprocess(firstString, zod.coerce.string())
  .transform((s) => s.trim() || undefined)
  .optional()
  .describe('Filter customers by key.\nCase-insensitive partial match (substring).\nEmpty/whitespace-only values are ignored.')

api/client/javascript/src/client/schemas.ts (2)

10680-10680: Clarify “partial” to “substring” and add an example for unambiguous behavior.

“Partial match” can be read as prefix, infix, or fuzzy. If the backend uses plain substring containment, let’s say so and include a short example to set expectations.

Apply this diff:

- *     Case-insensitive partial match. */
+ *     Case-insensitive substring match. For example, key=acme matches "ACME", "acme-co", and "myacme123". */

---

15080-15080: Mirror the same clarification and example in the operations interface.

Keep wording consistent across the components and operations sections to avoid divergent client docs.

Apply this diff:

- *     Case-insensitive partial match. */
+ *     Case-insensitive substring match. For example, key=acme matches "ACME", "acme-co", and "myacme123". */

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.