@blazeo.com/calendar-client 1.0.23 → 1.0.26

package/README.md

@@ -22,12 +22,26 @@ cd your-app && npm link @blazeo.com/calendar-client
 Configure once at app startup, then use models and their methods:
 
 ```js
-import { configure, setBaseUrl, setConsumer, CalendarModel, createRootStore } from '@blazeo.com/calendar-client';
+import {
+  configure,
+  setBaseUrl,
+  setConsumer,
+  setApiCredentials,
+  fetchAccessToken,
+  CalendarModel,
+  createRootStore,
+} from '@blazeo.com/calendar-client';
 
 configure({ baseUrl: 'https://your-appointment-api.example.com' });
 // or: setBaseUrl('https://localhost:7051');
 setConsumer('my-app');  // optional: sent as Consumer header (e.g. for lead source)
 
+// API JWT (for Authorized routes such as lead export)
+setApiCredentials('your-api-key', 'your-api-secret');
+await fetchAccessToken();
+// Or set a token you obtained elsewhere:
+// setAccessToken('eyJ...', '2026-05-19T12:00:00Z');
+
 // Calendar static methods (no store needed)
 const timezones = await CalendarModel.getTimeZones();
 const calendar = await CalendarModel.get('calendar-guid');
@@ -38,14 +52,80 @@ const cal = store.addCalendar({ calendarId: 'my-cal', name: 'My Calendar' });
 await cal.create(); // POST to backend
 ```
 
+### API JWT authentication
+
+The backend issues JWTs via `POST Api/Auth/Token` (`api_key` + `api_secret`). There is no refresh endpoint; when the token expires (~1 hour), call `fetchAccessToken()` again.
+
+| Function | Purpose |
+|----------|---------|
+| `setApiCredentials(apiKey, apiSecret)` | Store credentials for token exchange |
+| `fetchAccessToken()` | Get JWT from API and store on config |
+| `setAccessToken(token, expiresAtUtc?)` | Use a token you already have |
+| `ensureValidAccessToken()` | Fetch only if missing or near expiry |
+| `clearAuth()` | Clear token and credentials |
+
+All `reqGet` / `reqPost` calls automatically attach `Authorization: Bearer …` and re-issue the token before requests when credentials are configured.
+
+```js
+configure({ baseUrl: 'https://your-api', apiKey: 'key', apiSecret: 'secret' });
+await fetchAccessToken();
+await LeadModel.requestExport('company-key');
+```
+
 ## API overview
 
 - **CalendarModel (static):** `get`, `getByCompany`, `getTimeZones`, `getTimeZone`, `getParticipants`, `getMonth`, `getEvents`, etc.
 - **EventModel (instance):** `get`, `create`, `cancel`, `getCancellable`, `getAvailability`, `setReminder`
 - **FlowModel:** Same pattern as Calendar — `FlowModel.create({}, { env })` with no fields; static `get`, `getRaw`, `list`, `createFlow`, `updateFlow`, `delete`, `duplicate`, appearance/embed/public/preview helpers; instance methods mirror those using `flowId` on the snapshot
 - **LeadModel:** `LeadModel.create({}, { env })`; static `get`, `getRaw`, `getByEmail`, `getByCompany`; instance `get`, `getByEmail`, `getByCompany` (uses `leadId` / `email` / `companyKey` on the snapshot)
+- **ParticipantModel:** static `get`, `getByEmail`, `getByIds`, `getAll`, …; instance `getByEmail` uses `email` + `companyKey` on the snapshot (see `GET /participant/getbyemail`)
+- **AuthModel (calendar OAuth / Connect Calendar):** `getCalendarProviders`, `getAuthorizationUrl`, `getAuthorizationStatus`, `openOAuthPopup`, `onCalendarAuthMessage` — see [Calendar authorization flow](#calendar-authorization-direct-ui)
 - **RootStore:** `addCalendar`, `addEvent`
 
+### Calendar authorization (direct UI)
+
+When the user connects Google or Outlook from the Scheduling modal:
+
+```js
+import {
+  configure,
+  AuthModel,
+  CalendarEmailProvider,
+  CALENDAR_AUTH_MESSAGE_TYPE,
+} from '@blazeo.com/calendar-client';
+
+configure({ baseUrl: 'https://your-appointment-api.example.com' });
+
+const participantId = '...'; // logged-in participant GUID
+
+// Optional: already connected?
+const statusRes = await AuthModel.getAuthorizationStatus(participantId);
+if (statusRes.status === 'success' && statusRes.data?.isAuthorized) {
+  // show connected UI
+}
+
+// Load provider cards (Google / Gmail, Microsoft Outlook)
+const providersRes = await AuthModel.getCalendarProviders();
+const providers = providersRes.data; // [{ key: 'google', displayName: 'Google / Gmail', ... }, ...]
+
+// User clicks Google
+const urlRes = await AuthModel.getAuthorizationUrl(participantId, 'google');
+const popup = AuthModel.openOAuthPopup(urlRes.data.authorizationUrl);
+
+const unsubscribe = AuthModel.onCalendarAuthMessage(async (payload) => {
+  if (payload.status === 'success') {
+    const check = await AuthModel.getAuthorizationStatus(participantId);
+    if (check.data?.isAuthorized) {
+      // close modal, show success
+    }
+  }
+});
+
+// On modal unmount: unsubscribe(); popup?.close();
+```
+
+`email_provider` for `getAuthorizationUrl`: `google`, `gmail`, `1`, `outlook`, `microsoft`, or `2`.
+
 All methods return `Promise<{ status, data?, message? }>`. Check `response.status === 'success'` and use `response.data`.
 
 ## Samples

package/dist/index.d.ts

@@ -1,9 +1,59 @@
 /** @blazeo.com/calendar-client - type declarations */
 
-export function configure(env: { baseUrl?: string; consumer?: string; fetch?: typeof fetch; getDefaultOffset?: () => number }): void;
-export function getConfig(): { baseUrl?: string; consumer?: string; fetch?: typeof fetch; getDefaultOffset?: () => number } | null;
+export type AccessTokenResult = {
+  status: string;
+  message?: string;
+  accessToken?: string;
+  expiresAtUtc?: string | null;
+  tokenType?: string;
+};
+
+export type AuthState = {
+  accessToken?: string;
+  tokenExpiresAt?: string;
+  hasApiCredentials: boolean;
+};
+
+export function configure(env: {
+  baseUrl?: string;
+  consumer?: string;
+  fetch?: typeof fetch;
+  getDefaultOffset?: () => number;
+  accessToken?: string;
+  expiresAtUtc?: string;
+  tokenExpiresAt?: string;
+  expires_at_utc?: string;
+  apiKey?: string;
+  api_key?: string;
+  apiSecret?: string;
+  api_secret?: string;
+}): void;
+
+export function getConfig(): {
+  baseUrl?: string;
+  consumer?: string;
+  fetch?: typeof fetch;
+  getDefaultOffset?: () => number;
+  accessToken?: string;
+  tokenExpiresAt?: string;
+  hasApiCredentials?: boolean;
+} | null;
+
 export function setBaseUrl(baseUrl: string): void;
 export function setConsumer(consumer: string): void;
+export function setAccessToken(accessToken: string, expiresAtUtc?: string): void;
+export function clearAccessToken(): void;
+export function setApiCredentials(apiKey: string, apiSecret: string): void;
+export function clearApiCredentials(): void;
+export function clearAuth(): void;
+export function getAuth(): AuthState;
+export function fetchAccessToken(apiKey?: string, apiSecret?: string): Promise<AccessTokenResult>;
+export function ensureValidAccessToken(): Promise<string | undefined>;
+export function requestAccessToken(apiKey: string, apiSecret: string, opts?: { baseUrl?: string; fetch?: typeof fetch }): Promise<AccessTokenResult>;
+export function isAccessTokenExpired(expiresAtUtc?: string | number | Date | null, skewMs?: number): boolean;
+export function buildAuthHeaders(extra?: Record<string, string>): Record<string, string>;
+export const TOKEN_PATH: '/Api/Auth/Token';
+export const DEFAULT_TOKEN_REFRESH_SKEW_MS: number;
 export function getConfigStore(): unknown;
 
 export const ConfigModel: unknown;
@@ -79,6 +129,7 @@ export const CalendarParticipantModel: {
 };
 export const ParticipantModel: {
   get(participantId: string): Promise<unknown>;
+  getByEmail(email: string, companyKey: string): Promise<unknown>;
   getByIds(participantIds: string[] | string): Promise<unknown[] | null>;
   getAll(companyKey: string): Promise<unknown[] | null>;
   add(payload: object, calendarId?: string): Promise<unknown>;
@@ -246,6 +297,86 @@ export const LeadModel: {
   create(snapshot?: object, options?: { env?: object }): unknown;
 };
 
+export type CalendarProviderOption = {
+  emailProvider: number;
+  key: string;
+  name: string;
+  displayName: string;
+  description: string;
+  scope: string;
+  redirectUrl: string;
+};
+
+export type ParticipantAuthorizationUrl = {
+  participantId: string;
+  emailProvider: number;
+  providerKey: string;
+  authorizationUrl: string;
+  redirectUrl: string;
+};
+
+export type CalendarProviderAuthorizationState = {
+  emailProvider: number;
+  key: string;
+  name: string;
+  hasCredentials: boolean;
+  isAuthorized: boolean;
+  isSelected: boolean;
+};
+
+export type ParticipantAuthorizationStatus = {
+  participantId: string;
+  email: string;
+  emailProvider: number;
+  providerKey: string;
+  hasCredentials: boolean;
+  isAuthorized: boolean;
+  providers: CalendarProviderAuthorizationState[];
+};
+
+export const CALENDAR_AUTH_MESSAGE_TYPE: 'calendar-authorization';
+
+export const CalendarEmailProvider: {
+  Google: 1;
+  Microsoft: 2;
+  Default: 3;
+};
+
+export const AuthModel: {
+  CALENDAR_AUTH_MESSAGE_TYPE: typeof CALENDAR_AUTH_MESSAGE_TYPE;
+  EmailProvider: typeof CalendarEmailProvider;
+  getCalendarProviders(opts?: { host?: string }): Promise<{
+    status: string;
+    data?: CalendarProviderOption[];
+    message?: string;
+  }>;
+  getAuthorizationUrl(
+    participantId: string,
+    emailProvider: string | number,
+    opts?: { host?: string }
+  ): Promise<{
+    status: string;
+    data?: ParticipantAuthorizationUrl;
+    message?: string;
+  }>;
+  getAuthorizationStatus(participantId: string): Promise<{
+    status: string;
+    data?: ParticipantAuthorizationStatus;
+    message?: string;
+  }>;
+  openOAuthPopup(
+    authorizationUrl: string,
+    opts?: { width?: number; height?: number }
+  ): Window | null;
+  onCalendarAuthMessage(
+    handler: (payload: {
+      type: string;
+      status: 'success' | 'error';
+      message?: string;
+    }) => void
+  ): () => void;
+};
+
 export const CustomFieldModel: {
   getAll(calendarId: string): Promise<unknown[] | null>;
   getFieldType(fieldType: string): Promise<unknown>;
@@ -270,3 +401,4 @@ export const AttendeeStatus: Record<string, number>;
 export const RecurringFrequency: Record<string, number>;
 export const DayOfWeek: Record<string, number>;
 export const LocationType: Record<string, number>;
+export const EmailProvider: Record<string, number>;