@jphil/bookwhen-client 0.2.6 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # `@jphil/bookwhen-client`
 
-An API client library for the [Bookwhen](https://www.bookwhen.com) booking platform [API (v2)](https://api.bookwhen.com/v2), written in Typescript for NodeJS. \[wip\]!
+A universal API client library for the [Bookwhen](https://www.bookwhen.com) booking platform [API (v2)](https://api.bookwhen.com/v2), written in TypeScript for both NodeJS and browser environments.
 
 ## Table of Contents
 
@@ -19,7 +19,8 @@ You'll likely be at least somewhat familiar with the [Bookwhen](https://www.book
 
 ## Features
 
-- Provides an easy way to pull your data from Bookwhen for NodeJS environments
+- Provides an easy way to access Bookwhen API from both NodeJS and browsers
+- Browser-compatible with proper CORS handling
 - Provides fully typed methods for each model (so far just the Events model) provided in the Bookwhen API v2
 
 ## Installation
@@ -30,22 +31,32 @@ Install via pnpm:
 pnpm add @jphil/bookwhen-client
 ```
 
+As `axios` and `zod` are peer dependencies, ensure they are also installed in your project:
+
+```bash
+pnpm add axios zod
+# or npm install axios zod
+# or yarn add axios zod
+```
+
 ## Usage
 
+This library is distributed as an ES module. The following usage pattern applies to modern Node.js environments (with `type: "module"` in your `package.json` or when using `.mjs` files) and browser environments when using a bundler. For direct browser usage without a bundler, see the [Browser Usage](#browser-usage) section below.
+
 ```typescript
 // import the client factory
 import { createBookwhenClient } from '@jphil/bookwhen-client';
 
 // create the client
-const client = createBookwhenClient({ 
+const client = createBookwhenClient({
   apiKey: 'your-API-key',
-  debug: true  // Optional: enables request logging
+  debug: true, // Optional: enables request logging
 });
 
 // Get a single event
 const event = await client.events.getById({
   eventId: 'some-id',
-  includes: ['location', 'tickets']  // Optional: include related resources
+  includes: ['location', 'tickets'], // Optional: include related resources
 });
 
 // get all events
@@ -53,27 +64,112 @@ const events = await client.events.getMultiple();
 
 // get all events in 2025 tagged with 'workshop'
 const events_2025 = await client.events.getMultiple({
-  filters: {  // Optional: filter by various 
+  filters: {
+    // Optional: filter by various
     from: '20250101',
     to: '20251231',
-    tag: ['workshop']
+    tag: ['workshop'],
   },
-  includes: ['location']   // Optional: Include related resources
+  includes: ['location'], // Optional: Include related resources
 });
-
 ```
 
 (N.B. Ensure you wrap the above statements in try/catch blocks to catch errors which could be thrown)
 
-Valid filters and includes for each method are detailed in the [API v2 docs](https://petstore.swagger.io/?url=https://api.bookwhen.com/v2/openapi.yaml) 
+Valid filters and includes for each method are detailed in the [API v2 docs](https://petstore.swagger.io/?url=https://api.bookwhen.com/v2/openapi.yaml)
 
 Services for the other models in the API are in the pipeline.
 
-N.B. This library is still a pre-1.0.0 WIP, please use accordingly, and pls make issues for any bugs!
+N.B. This library is still a pre-1.0.0 WIP, please use accordingly, and pls submit issues for any bugs!
+
+## Browser Usage
+
+The client is well-suited for browser environments.
+
+### With a Bundler (Recommended for Browser Projects)
+
+If you are using a JavaScript bundler (like Webpack, Rollup, Vite, Parcel, etc.) in your browser project, you can import and use the client as shown in the main [Usage](#usage) section:
+
+```typescript
+import { createBookwhenClient } from '@jphil/bookwhen-client';
+// ... rest of your code
+```
+
+Ensure that `axios` and `zod` are also installed in your project, as they are peer dependencies. Your bundler will typically handle resolving these.
+
+### Directly with `<script type="module">` (Advanced)
+
+For direct usage in a browser via `<script type="module">` without a bundler, you will need to:
+
+1. Ensure ES module versions of `axios` and `zod` are accessible to your page (e.g., served locally or via a CDN).
+2. Use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to tell the browser how to resolve the module specifiers for `@jphil/bookwhen-client`, `axios`, and `zod`.
+
+Example import map:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "@jphil/bookwhen-client": "/node_modules/@jphil/bookwhen-client/dist/index.es.js",
+      "axios": "/node_modules/axios/dist/esm/axios.js",
+      "zod": "/node_modules/zod/lib/index.mjs"
+    }
+  }
+</script>
+<script type="module">
+  import { createBookwhenClient } from '@jphil/bookwhen-client';
+  // ...
+</script>
+```
+
+Note: The exact paths in the import map will depend on how you serve these dependencies. Usage with a bundler is generally simpler for browser projects.
+
+### Important Note on API Keys in Client-Side Usage
+
+When using this library in a browser (client-side), your Bookwhen API key will necessarily be included in the client-side code and thus visible.
+
+- It is crucial to use an API key that has the minimum necessary permissions for the operations you intend to perform from the client-side.
+- This library enables access to Bookwhen API endpoints based on the permissions granted to the API key you provide.
+
+## Error Handling
+
+The library provides comprehensive error handling that works consistently in both Node.js and browser environments. Custom error objects thrown by the library will have the following properties:
+
+- `code`: An error code string identifying the type of error (e.g., `NETWORK_ERROR`, `API_ERROR`).
+- `message`: A human-readable description of the error.
+- `isBrowser`: A boolean indicating if the error occurred in a browser environment.
+- `context`: An object containing additional details, which may include the original error, status codes, etc.
+- `timestamp`: The time the error occurred.
+
+### Error Types
+
+- `NETWORK_ERROR`: Indicates a failure in API communication (e.g., DNS resolution, connection refused).
+- `SECURITY_ERROR`: Specific to browsers, indicates security restrictions prevented API access (e.g., CORS issues not handled by the server, mixed content).
+- `API_ERROR`: The Bookwhen API returned an error response (e.g., 4xx or 5xx status code). The `context` may include `statusCode` and `responseData`.
+- `CONFIG_ERROR`: The client was configured incorrectly (e.g., missing API key).
+- `UNKNOWN_ERROR`: An unexpected error occurred within the library.
+
+Example:
+
+```typescript
+try {
+  await client.events.getById({ eventId: 'invalid-id' });
+} catch (error: any) {
+  // It's good practice to type the error if you have custom error types defined
+  console.error(`Error Code: ${error.code}`);
+  console.error(`Message: ${error.message}`);
+  if (error.code === 'API_ERROR') {
+    console.error('API Error Details:', error.context?.responseData);
+  } else if (error.code === 'NETWORK_ERROR') {
+    // Handle network issues, maybe retry or inform user
+  }
+  // Other error handling...
+}
+```
 
 ## Configuration
 
-Required configuration options:
+Required configuration:
 
 - **apiKey**: Your Bookwhen API key (required)
 
@@ -85,6 +181,43 @@ API keys can be generated in the [API tokens setup area of your Bookwhen account
 
 Please see the docs in the CONTRIBUTIONS.md file, thanks!
 
+## Mainainter release process
+
+[refining]
+
+From main branch on local:
+
+- Pull latest code
+- git checkout -b some-new-branch
+- git commit -m 'feat(context): my latest work on feature x'
+- git push, copy URL
+
+On github
+
+> Open PR on github
+> Perfect, merge when checks pass
+
+On local:
+
+- checkout main
+- git pull
+- git branch -d release (so we have a clean release branch)
+- git checkout -b release
+- pnpm changeset (provide changelog message, commit will occur after)
+- pnpm changeset version (bumps version numbers, and updates changelog, and commits >>> note new version number)
+- git push
+
+On github:
+
+- Open PR main <- release on github
+  > Perfect, merge when checks pass (check why no build)
+
+On local:
+
+- git checkout main
+- git tag -a vx.x.x -m 'release vx.x.x'
+- git push origin vx.x.x <<<< RELEASE to github and NPM
+
 ## Roadmap
 
 - Proceed towards a 1.0.0 with community feedback.
@@ -92,9 +225,7 @@ Please see the docs in the CONTRIBUTIONS.md file, thanks!
 
 ### Todos
 
-- [] create e2e test suite with github action workflow
-- [] put Zod in place in more areas to strengthen runtime type guards
-- [] write services for the other models in the API
+@see the issue queue.
 
 ## License
 

package/dist/index.d.ts

@@ -1,3 +1,199 @@
-export * from './types/GlobalTypes.js';
-export * from './services/event/EventInterfaces.js';
-export { createBookwhenClient } from './client/BookwhenClient.js';
+import { AxiosInstance } from 'axios';
+import { z } from 'zod';
+
+/**
+ * Client for the Bookwhen API.
+ *
+ * @see https://petstore.swagger.io/?url=https://api.bookwhen.com/v2/openapi.yaml#/ClassPass/get_class_passes__class_pass_id_
+ */
+declare class BookwhenClient {
+    private axiosInstance;
+    private eventService?;
+    private readonly isBrowser;
+    /**
+     * Creates a new instance of the BookwhenClient class.
+     * @param axiosInstance - Configured Axios instance for making HTTP requests.
+     * @throws Error if axiosInstance is not provided.
+     */
+    constructor(axiosInstance: AxiosInstance);
+    /**
+     * Gets the EventService instance.
+     *
+     * Available methods:
+     * - getById(params: GetEventByIdParams): Promise<BookwhenEvent>
+     * - getMultiple(params: GetMultipleEventsParams): Promise<BookwhenEvent[]>
+     *
+     * @returns The EventService instance.
+     */
+    get events(): EventService;
+}
+
+declare interface BookwhenClientOptions {
+    apiKey: string;
+    baseURL?: string;
+    debug?: boolean;
+}
+
+export declare interface BookwhenError {
+    code: 'NETWORK_ERROR' | 'SECURITY_ERROR' | 'API_ERROR' | 'CONFIG_ERROR' | 'UNKNOWN_ERROR';
+    message: string;
+    isBrowser: boolean;
+    context?: {
+        browser?: {
+            isSecure?: boolean;
+            userAgent?: string;
+        };
+        timestamp: number;
+    };
+}
+
+declare interface BookwhenEvent {
+    id: string;
+    type: string;
+    attributes: EventAttributes;
+}
+
+/**
+ * Creates an instance of Axios with the provided API key.
+ * @param apiKey - The API key used for authentication.
+ * @returns The Axios instance.
+ */
+export declare function createBookwhenClient(options: BookwhenClientOptions): BookwhenClient;
+
+declare interface EventAttributes {
+    title: string;
+    details: string;
+    all_day: boolean;
+    start_at: string;
+    end_at: string;
+    attendee_limit: number;
+    attendee_count: number;
+    waiting_list: boolean;
+    max_tickets_per_booking: number;
+    tags: string[];
+    event_image: EventImage;
+}
+
+export declare type EventFilters = {
+    [K in keyof EventFiltersMap]?: EventFiltersMap[K];
+};
+
+declare interface EventFiltersMap {
+    calendar?: string[];
+    entry?: string[];
+    location?: string[];
+    tag?: string[];
+    title?: string[];
+    detail?: string[];
+    from?: string;
+    to?: string;
+    compact?: boolean;
+}
+
+declare interface EventImage {
+    image_url: string;
+    alt_ratio_16x9_1x_url: string;
+    alt_ratio_16x9_2x_url: string;
+    alt_ratio_16x9_3x_url: string;
+    alt_ratio_4x3_1x_url: string;
+    alt_ratio_4x3_2x_url: string;
+    alt_ratio_4x3_3x_url: string;
+    alt_ratio_1x1_1x_url: string;
+    alt_ratio_1x1_2x_url: string;
+    alt_ratio_1x1_3x_url: string;
+}
+
+export declare type EventResource = 'location' | 'attachments' | 'tickets' | 'tickets.events' | 'tickets.class_passes';
+
+/**
+ * Service class for managing events in the Bookwhen API.
+ */
+declare class EventService implements IEventService {
+    private axiosInstance;
+    /**
+     * Initializes EventService with an Axios instance for dependency injection.
+     * @param axiosInstance - The Axios instance to use for API requests.
+     */
+    constructor(axiosInstance: AxiosInstance);
+    /**
+     * Retrieves a single event by its ID from the Bookwhen API.
+     *
+     * @param {Object} param - The parameters for retrieving an event.
+     * @param {string} param.eventId - The ID of the event to retrieve.
+     * @param {string} [param.include] - Optional parameter to include additional data.
+     * @returns {Promise<BookwhenEvent>} A Promise that resolves to the BookwhenEvent object.
+     */
+    getById(params: z.infer<typeof GetEventByIdParamsSchema>): Promise<BookwhenEvent>;
+    /**
+     * Retrieves multiple events based on filtering and pagination parameters.
+     *
+     * @param {GetMultipleEventsParams} params - Optional parameters for filtering and pagination.
+     * @return {Promise<BookwhenEvent[]>} A Promise that resolves to an array of BookwhenEvent objects.
+     */
+    getMultiple(params?: GetMultipleEventsParams): Promise<BookwhenEvent[]>;
+}
+
+export declare interface Filters {
+    [key: string]: string | string[] | boolean;
+}
+
+/**
+ * Parameters for querying a single event from the Bookwhen API, including optional include parameter.
+ * @param eventId The unique identifier of the event.
+ * @param include Optional parameter to include additional data.
+ */
+export declare interface GetEventByIdParams {
+    eventId: string;
+    includes?: EventResource[];
+}
+
+declare const GetEventByIdParamsSchema: z.ZodObject<{
+    eventId: z.ZodString;
+    includes: z.ZodOptional<z.ZodArray<z.ZodEnum<["location", "attachments", "tickets", "tickets.events", "tickets.class_passes"]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    eventId: string;
+    includes?: ("location" | "attachments" | "tickets" | "tickets.events" | "tickets.class_passes")[] | undefined;
+}, {
+    eventId: string;
+    includes?: ("location" | "attachments" | "tickets" | "tickets.events" | "tickets.class_passes")[] | undefined;
+}>;
+
+/**
+ * Represents the parameters for getting multiple events.
+ * @param filter The filter parameters to apply to the query.
+ * @param include The data to side load and include with the returned events.
+ */
+export declare interface GetMultipleEventsParams {
+    filters?: EventFilters;
+    includes?: EventResource[];
+}
+
+export declare interface HttpStatus {
+    code: number;
+    message: string;
+}
+
+/**
+ * Interface for services handling events via the Bookwhen API V2.
+ */
+export declare interface IEventService {
+    /**
+     * Retrieves a single event by its ID.
+     * @param eventId The unique identifier of the event.
+     * @param include Optional parameter to include additional data.
+     * @returns A Promise that resolves to an Event object, as defined by the Bookwhen API data structure.
+     */
+    getById(params: GetEventByIdParams): Promise<BookwhenEvent>;
+    /**
+     * Retrieves multiple events based on specified parameters.
+     * @param params Optional parameters to filter and control the list of returned events, according to what the Bookwhen API supports.
+     * @returns A Promise that resolves to an array of Event objects.
+     */
+    getMultiple?(params?: GetMultipleEventsParams): Promise<BookwhenEvent[]>;
+}
+
+export declare type Resource = string;
+
+export declare type Resources = Resource[];
+
+export { }