Trials

[pixelmund]

Closes #21

Don't know if bumping the peer dependency is okay but it's required for trials to work, should probably be a minor release then.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Summary by CodeRabbit

Release Notes

• New Features

  • Added trial period configuration for checkouts with configurable intervals (daily, weekly, monthly, yearly) and duration.
  • Subscriptions and products now track trial period information including start and end dates.
  • Improved subscription filtering to automatically exclude expired trial periods.

• Chores

  • Updated peer dependency requirements for SDK library.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Added free trial support to the Convex Polar client library. Changes include trial-related fields to product and subscription schemas, new trial parameters (trialInterval, trialIntervalCount) to checkout APIs, updated subscription filtering logic to exclude expired trials, and new trial props to the React CheckoutLink component. Peer dependency updated to @polar-sh/sdk >=0.35.4.

Changes

Cohort / File(s)	Change Summary
Peer Dependency Update package.json	Updated @polar-sh/sdk peer dependency from >=0.32.11 to >=0.35.4
Schema Extensions src/component/schema.ts	Added trial-related fields to products schema: trialInterval (day|week|month|year|null) and trialIntervalCount (number|null); added to subscriptions schema: trialStart and trialEnd (string|null)
Utility Conversions src/component/util.ts	Updated convertToDatabaseSubscription to include trialStart and trialEnd fields; updated convertToDatabaseProduct to include trialInterval and trialIntervalCount fields
API Client Methods src/client/index.ts	Extended createCheckoutSession and generateCheckoutLink to accept optional trialInterval and trialIntervalCount parameters; updated argument validation schema to include these fields
Subscription Filtering src/component/lib.ts	Modified listUserSubscriptions filtering logic to additionally exclude trialing subscriptions with past trialEnd dates
React Component src/react/index.tsx	Added trialInterval and trialIntervalCount props to CheckoutLink component; forwarded these props to generateCheckoutLink API call

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Verify trial field types and nullability are consistent across schema definitions, conversion utilities, and API parameters
• Validate the subscription filtering logic correctly handles both endedAt expiration and trialEnd expiration for trialing subscriptions
• Confirm API parameter validation in src/client/index.ts matches the schema requirements for trial fields
• Ensure React component's new props are properly destructured and passed without being added to the effect dependency array (as noted in the diff)

Poem

🐰 Trials now sprout in Polar's garden so bright,
Parameters bloom from trialInterval light,
Subscriptions track start and end, oh what delight!
Filters catch expired trials, keeping things right,
React components dance with their props held tight! 🌾✨

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Trials' is vague and generic, using a single non-descriptive word that doesn't convey what specific functionality or changes are being introduced.	Use a more specific title that explains the main change, such as 'Add trial support with product and subscription fields' or 'Implement free trials functionality'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	All coding objectives from issue #21 are implemented: trial fields added to products (trialInterval, trialIntervalCount) and subscriptions (trialStart, trialEnd), peer dependency updated, and trial-related filtering logic added.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing trial support as specified in issue #21; no unrelated modifications detected across modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1da2d45 and 8cd0934.

📒 Files selected for processing (6)

• package.json (1 hunks)
• src/client/index.ts (4 hunks)
• src/component/lib.ts (1 hunks)
• src/component/schema.ts (2 hunks)
• src/component/util.ts (2 hunks)
• src/react/index.tsx (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/react/index.tsx (1)

src/client/index.ts (1)

• PolarComponentApi (48-50)

🔇 Additional comments (6)

src/component/lib.ts (1)

163-171: LGTM!

The filtering logic correctly excludes expired trials by checking both the existing endedAt condition and the new trialing subscription expiry. The use of optional chaining for trialEnd is appropriate since it's an optional field.

src/component/util.ts (1)

39-40: LGTM!

The trial field additions follow existing conversion patterns consistently, using toISOString() for date fields and proper null handling with the nullish coalescing operator.

Also applies to: 65-66

src/component/schema.ts (1)

29-38: LGTM!

The trial field additions to the schema are well-structured and backward compatible. All fields are properly marked as optional, and the types align with the API surface across other files.

Also applies to: 95-96

src/client/index.ts (2)

312-346: LGTM!

The generateCheckoutLink action correctly extends the API surface to accept trial parameters with proper validation. The implementation forwards these values through to the checkout session creation flow consistently.

---

99-164: SDK parameter support confirmed.

The implementation correctly adds trialInterval and trialIntervalCount to the checkout session creation flow. The @polar-sh/sdk TypeScript SDK supports these parameters in checkoutsCreate(), with trialInterval accepting "day" | "week" | "month" | "year" | null and trialIntervalCount accepting integer | null. The types and forwarding in the code are correct.

package.json (1)

73-73: Verify the SDK version and check for breaking changes.

The peer dependency bump from >=0.32.11 to >=0.35.4 spans multiple minor versions. The @polar-sh/sdk is in beta and may contain breaking changes between versions. Ensure this version exists and doesn't introduce incompatibilities, particularly with the trial feature requirements mentioned in the PR.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}