Version 2.0.0

v2.0.0

The major version bump reflects a breaking change to the shape of the impact-reporting types (see Breaking Changes below).

Added

• Restore Coral API: New restoreCoral() method to fund coral reef restoration → POST /v1/restore_coral
  • amount is the number of coral fragments to restore (1–10,000,000)
  • Optional customerEmail, customerName, notify, and metadata
  • Returns RestoreCoralResponse containing userID, coralRestored, timeUTC, customer
• Cancel Impact API: New cancelImpact() method to cancel and reverse a previously created impact → POST /v1/cancel_impact
  • Designed for refund flows — removes the impact from /impact totals and reflects on /track
  • Idempotent: repeat calls return "impact was already cancelled" without double-reversing aggregates
  • Params: userID (e.g. "U1234"), timeUTC (ISO 8601), optional reason (max 200 chars)
  • Returns CancelImpactResponse including userID, timeUTC, cancelledOn, message, and the reversed amount for the impact type (treePlanted / wasteRemoved / carbonCaptured / coralRestored / moneyDonated), plus optional reason and category
• Donation categories: donateMoney() now accepts an optional category parameter (e.g. "veterans", "animals", "climate") and returns category in the response
• Metadata support: All impact actions (plantTree, cleanOcean, captureCarbon, donateMoney, restoreCoral) accept an optional metadata object of string→string key-value pairs
  • Limits: up to 20 pairs, keys ≤ 40 chars, values ≤ 500 chars; reserved keys "gift" and "widgetID" are not allowed
  • Echoed back on record responses when present
• Coral in reporting: coralRestored is now returned across the read endpoints:
  • getImpact() — top-level total plus in the userImpact / customerImpact breakdowns
  • getDailyImpact() — per-day coralRestored
  • getRecords() / getCustomerRecords() — filter with filterBy: "coral_restored"; coral records returned as CoralRestoredRecord / CoralRestoredRecordWithCustomer
  • track() — coralRestored when applicable
• New Types: RestoreCoralParams, RestoreCoralResponse, CancelImpactParams, CancelImpactResponse, CoralRestoredRecord, CoralRestoredRecordWithCustomer, and the Metadata alias (Record<string, string>)

Breaking Changes

• coralRestored added to ImpactBreakdown, ImpactResponse, and DailyImpactRecord as a new required field, positioned before moneyDonated to match the API field order (treePlanted → wasteRemoved → carbonCaptured → coralRestored → moneyDonated). TypeScript code that constructs these objects directly must add the new field; code that only consumes SDK responses is unaffected at runtime.

Changed

• TrackResponse: added coralRestored, cancelledOn, and cancellationReason fields (the latter two populated for cancelled impacts)
• DonateMoneyParams / DonateMoneyResponse: added category; DonateMoneyParams also gained metadata
• PlantTreeParams, CleanOceanParams, CaptureCarbonParams: added metadata
• Impact record types gained an optional metadata field (present only when the API returns it)
• ImpactRecord and CustomerImpactRecord unions now include the coral record types
• Enhanced test suite with full coverage for restoreCoral(), cancelImpact(), the category and metadata parameters, and coral mapping across getImpact() / getRecords()

Documentation

• Updated README with new Restore Coral, Cancel Impact, and Metadata sections
• Added category examples to the Donate Money section
• Documented coralRestored in the Records, Impact, and Track sections, and cancelledOn / cancellationReason in the Track response fields

Full Changelog: v1.3.0...v2.0.0