add: v30 analytics + synonym_set/items APIs

[harisarang]

Change Summary

Introduce Analytics v30+ API alongside legacy AnalyticsV1, add Analytics Events GET endpoint, make analytics event type optional, and deprecate Synonym/Synonyms in favor of Synonym Sets. Tests updated with version gating via isV30OrAbove.

Changes

• Added Features

  • Analytics (v30+) client surface
    • New Analytics that follows the OpenAPI schema, exposed as client.analytics.
    • AnalyticsRules and AnalyticsRule (v30+) with:
      • create() supporting single or array payloads (POST /analytics/rules).
      • upsert(name, ...) (PUT /analytics/rules/{ruleName}).
      • retrieve(ruleTag?) with rule_tag filter support.
    • Files:
      • src/Typesense/Analytics.ts
      • src/Typesense/AnalyticsRules.ts
      • src/Typesense/AnalyticsRule.ts
  • Analytics Events GET endpoint (v30+)
    • AnalyticsEvents.retrieve({ user_id, name, n }) (GET /analytics/events).
    • Response typed as AnalyticsEventsRetrieveSchema.
    • Files:
      • src/Typesense/AnalyticsEvents.ts (new retrieve + response type)
  • Analytics Event schema
    • AnalyticsEventCreateSchema.type is now optional.
    • Files:
      • src/Typesense/AnalyticsEvent.ts

• Backward Compatibility (V1)

  • Legacy Analytics (pre-v30)
    • AnalyticsV1 keeps existing behavior, moved rule classes under V1:
      • AnalyticsRuleV1, AnalyticsRulesV1
    • client.analyticsV1 continues to work (legacy).
    • Files:
      • src/Typesense/AnalyticsV1.ts
      • src/Typesense/AnalyticsRuleV1.ts
      • src/Typesense/AnalyticsRulesV1.ts

• Deprecations

  • AnalyticsV1
    • One-time runtime warning mentioning deprecation starting with Typesense Server v30; prefer client.analytics.
    • File: src/Typesense/AnalyticsV1.ts
  • Synonym/Synonyms
    • One-time runtime warnings advising migration to Synonym Sets (synonym_sets) starting with v30.
    • Files:
      • src/Typesense/Synonyms.ts
      • src/Typesense/Synonym.ts

• Test Coverage

  • Analytics Rules (split by server version)
    • Legacy (pre-v30): typesense.analyticsV1.rules() paths remain, tests gated with describe.skipIf(await isV30OrAbove(...)).
    • New (v30+): typesense.analytics.rules() tests for:
      • create() (POST)
      • upsert() (PUT)
      • retrieve() with and without rule_tag
    • File: test/Typesense/AnalyticsRules.spec.ts
  • Analytics Rule (single)
    • Legacy tests moved to V1 surface and gated by version.
    • File: test/Typesense/AnalyticsRule.spec.ts
  • Analytics Events
    • Existing create tests updated to new error message behavior.
    • Added .retrieve test gated to v30+ using describe.skipIf(!(await isV30OrAbove(typesense))).
    • File: test/Typesense/AnalyticsEvents.spec.ts
  • Version gating utility
    • isV30OrAbove() continues to be used for conditional test execution.
    • File: test/utils.ts (unchanged, newly referenced)

Migration Notes

• Use client.analytics (v30+) instead of client.analyticsV1.
• For analytics rules:
  • Use analytics.rules().create(payload) for POST (single or array).
  • Use analytics.rules().upsert(ruleName, payload) for PUT.
  • Use analytics.rules().retrieve(ruleTag?) to fetch all rules (optionally filtered).
• For analytics events:
  • Use analytics.events().retrieve({ user_id, name, n }) for recent events.
  • type field in create() payload is optional.
• Synonyms:
  • Synonym/Synonyms are deprecated as of v30; migrate to Synonym Sets APIs.

PR Checklist

• I have read and signed the Contributor License Agreement.](add: v30 analytics + synonym_set/items APIs #312 (comment))

[tharropoulos]

I'd say moving the new API to their own V2 files or rename the old ones to v1, to maintain backwards compatibility would be better than deprecated the old API altogether. Scatch that.

[harisarang]

I have renamed the old ones to V1