feat(scheduler): add GET /v3/scheduling/availability endpoint support

[yun-jay]

Summary

Adds support for the GET /v3/scheduling/availability endpoint, which returns available time slots for a given scheduling configuration within a time range. This was missing from the scheduling API support that already included sessions, bookings, and configurations.

Changes

• Added AvailabilityTimeSlot, AvailabilityResponse, and GetAvailabilityQueryParams types to src/models/scheduler.ts
• Created src/resources/availability.ts with SchedulerAvailability resource class and list method
• Registered availability sub-resource in src/resources/scheduler.ts
• Added tests in tests/resources/availability.spec.ts

Usage

const availability = await nylas.scheduler.availability.list({
  queryParams: {
    startTime: '1659367800',
    endTime: '1659369600',
    configurationId: 'config123',
  },
});

License

I confirm that this contribution is made under the terms of the MIT license and that I have the authority necessary to make this contribution on behalf of its copyright owner.

---

Note

Low Risk
Low risk: additive API surface (new resource/types) with no changes to existing scheduling flows beyond wiring a new sub-resource.

Overview
Adds a new scheduler.availability.list resource that calls GET /v3/scheduling/availability with time-range/config query params and returns typed availability time slots.

Updates scheduler models with AvailabilityTimeSlot/AvailabilityResponse/GetAvailabilityQueryParams, wires the new sub-resource into Scheduler, and adds a unit test asserting the request shape and overrides handling.

^{Written by Cursor Bugbot for commit c86729a. This will update automatically on new commits. Configure here.}

[cursor]

Duplicate GetAvailabilityParams name across resource files

Low Severity

The new GetAvailabilityParams interface in src/resources/availability.ts has the same name as the existing GetAvailabilityParams in src/resources/calendars.ts, but with a different structure (queryParams vs requestBody). This creates ambiguity for IDE auto-imports and requires aliasing if both are needed in the same file. A more specific name like GetSchedulerAvailabilityParams or ListAvailabilityParams would avoid confusion.

 

[radenkovic]

@yun-jay thank you for contributing! I am going to merge #716 which covers the same functionality and release the new version.

[radenkovic]

Closing in favor of #716.

[yun-jay]

Hey @radenkovic why does #716 solve this? I would like to be able to call the endpoint /v3/scheduling/availability to get the availability of a scheduler and not of a calendar or am I overseeing something?

I'm currently doing:

 nylas.apiClient.request({
    method: 'GET',
    path: '/v3/scheduling/availability',
    queryParams,
  });

but type safety would be really appreciated :)

[radenkovic]

@yun-jay thanks for pointing out, you are right! addressing this today.

[radenkovic]

@yun-jay this is addressed in #720. I will do a release later today, thank you very much for stepping in!

[yun-jay]

@radenkovic Awesome, thank you very much!

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Availability time slot timestamps likely wrong type

Medium Severity

AvailabilityTimeSlot.startTime and endTime are typed as number, but the analogous TimeSlot interface in models/availability.ts (used for calendar availability — a very similar endpoint) types these same fields as string. The Nylas SDK reference documentation also confirms that availability time slot timestamps are strings. If the scheduling availability endpoint follows the same convention, consumers relying on number arithmetic will get unexpected results at runtime since the actual values would be strings.