@basementuniverse/jsonpad-realtime-sdk 1.0.0

package/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "explicit"
+  },
+  "[typescript]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gordon Larrigan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# JSONPad Realtime SDK
+
+This package allows you to connect to JSONPad Realtime and get realtime updates when your lists or items change.
+
+## Installation
+
+```bash
+npm install @basementuniverse/jsonpad-realtime-sdk
+```
+
+## Usage
+
+Create an instance of the JSONPad Realtime SDK and pass in your API token:
+
+Node (JS):
+
+```js
+const JSONPadRealtime = require('@basementuniverse/jsonpad-realtime-sdk').default;
+
+const jsonpadRealtime = new JSONPadRealtime('your-api-token');
+```
+
+Node (TS):
+
+```ts
+import JSONPadRealtime from '@basementuniverse/jsonpad-realtime-sdk';
+
+const jsonpadRealtime = new JSONPadRealtime('your-api-token');
+```
+
+Browser:
+
+```html
+<script src="jsonpad-realtime-sdk.js"></script>
+<script>
+  const jsonpadRealtime = new JSONPadRealtime.default('your-api-token');
+</script>
+```
+
+Next, start listening for events on your lists or items:
+
+```js
+jsonpadRealtime.listen(
+  [
+    'list-created',
+    'list-updated',
+    'list-deleted',
+    'item-created',
+    'item-updated',
+    'item-restored',
+    'item-deleted',
+  ]
+);
+```
+
+Attach event listeners to the JSONPad Realtime SDK instance:
+
+```js
+jsonpadRealtime.addEventListener('list-created', e => {
+  console.log(`A list called ${e.detail.model.name} was created!`);
+});
+```
+
+If you want to stop listening for events and disconnect from the server, you can call the `close` method:
+
+```js
+jsonpadRealtime.close();
+```
+
+## `listen()` method
+
+The `listen()` method takes an array of event types to listen for. You can pass in any of the following event types:
+
+- `list-created`
+- `list-updated`
+- `list-deleted`
+- `item-created`
+- `item-updated`
+- `item-restored`
+- `item-deleted`
+
+You can also optionally pass in an array of list ids and item ids to listen for.
+
+You can include `*` in the list ids and item ids arrays to listen for all lists or items.
+
+```js
+jsonpadRealtime.listen(
+  [
+    'list-created',
+    'list-updated',
+    'list-deleted',
+    'item-created',
+    'item-updated',
+    'item-restored',
+    'item-deleted',
+  ],
+  [
+    '86059de7-9b16-4469-a630-23c8f69944b6',
+    'a2c706a6-5212-4e8a-92ad-bce1beea153f',
+  ],
+  [
+    'e0bc4797-303a-49ff-b7b4-18781cc2460e',
+    '06ad5a22-c002-4c67-92bc-83ec85014461',
+  ]
+);
+```
+
+## Event types
+
+- `list-created`: A list was created.
+- `list-updated`: A list was updated.
+- `list-deleted`: A list was deleted.
+- `item-created`: An item was created.
+- `item-updated`: An item was updated.
+- `item-restored`: An item was restored.
+- `item-deleted`: An item was deleted.
+
+## Event object
+
+The event object passed to the event listener has the following properties:
+
+```ts
+{
+  type: string;
+  detail: {
+    listId: string;
+    itemId: string;
+    model: any; // This will be a List or Item, depending on the event type
+  };
+}
+```

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@basementuniverse/jsonpad-realtime-sdk",
+  "version": "1.0.0",
+  "description": "JSONPad Realtime SDK for Node and browser",
+  "author": "Gordon Larrigan <gordonlarrigan@gmail.com> (https://gordonlarrigan.com)",
+  "license": "MIT",
+  "homepage": "https://github.com/basementuniverse/jsonpad-realtime-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/basementuniverse/jsonpad-realtime-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/basementuniverse/jsonpad-realtime-sdk/issues"
+  },
+  "main": "build/jsonpad-realtime-sdk.js",
+  "types": "build/jsonpad-realtime-sdk.d.ts",
+  "scripts": {
+    "build": "rollup -c && npm run clean",
+    "clean": "rm -rf build/types build/utilities build/models build/index.d.ts build/constants.d.ts"
+  },
+  "devDependencies": {
+    "-": "^0.0.1",
+    "@rollup/plugin-commonjs": "^28.0.1",
+    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.1",
+    "rollup": "^4.24.3",
+    "rollup-plugin-dts": "^6.1.1",
+    "save-dev": "^0.0.1-security",
+    "tslib": "^2.8.1"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.1"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,2 @@
+export const API_URL = 'https://realtime.jsonpad.io';
+export const API_TOKEN_HEADER = 'x-api-token';

package/src/jsonpad-realtime.ts

@@ -0,0 +1,92 @@
+import { io, Socket } from 'socket.io-client';
+import * as constants from './constants';
+import { EventType, MessageType } from './types';
+
+export class JSONPadRealtime extends EventTarget {
+  private static readonly connected = new Event('connected');
+  private static readonly disconnected = new Event('disconnected');
+
+  private socket: Socket | null = null;
+
+  /**
+   * Create a new JSONPad realtime client instance
+   */
+  public constructor(private token: string) {
+    super();
+  }
+
+  /**
+   * Close the connection to the realtime server
+   */
+  public close() {
+    if (this.socket && this.socket.connected) {
+      this.socket.removeAllListeners();
+      this.socket.close();
+    }
+  }
+
+  /**
+   * Start listening for realtime events
+   */
+  public listen(
+    eventTypes: EventType[],
+    listIds?: string[],
+    itemIds?: string[]
+  ) {
+    if (this.socket && this.socket.connected) {
+      this.socket.removeAllListeners();
+      this.socket.close();
+    }
+
+    if (eventTypes.length === 0) {
+      throw new Error('At least one event type must be provided');
+    }
+
+    this.socket = io(
+      `${constants.API_URL}?${new URLSearchParams({
+        eventTypes: eventTypes.join(','),
+        listIds: listIds?.join(',') ?? '',
+        itemIds: itemIds?.join(',') ?? '',
+      })}`,
+      {
+        extraHeaders: {
+          [constants.API_TOKEN_HEADER]: this.token,
+        },
+      }
+    );
+
+    this.socket.on('connect', this.handleConnected.bind(this));
+    this.socket.on('disconnect', this.handleDisconnected.bind(this));
+    this.socket.on('error', this.handleError.bind(this));
+    this.socket.on('list-created', this.handleEvent.bind(this, 'list-created'));
+    this.socket.on('list-updated', this.handleEvent.bind(this, 'list-updated'));
+    this.socket.on('list-deleted', this.handleEvent.bind(this, 'list-deleted'));
+    this.socket.on('item-created', this.handleEvent.bind(this, 'item-created'));
+    this.socket.on('item-updated', this.handleEvent.bind(this, 'item-updated'));
+    this.socket.on('item-deleted', this.handleEvent.bind(this, 'item-deleted'));
+  }
+
+  private handleConnected() {
+    this.dispatchEvent(JSONPadRealtime.connected);
+  }
+
+  private handleDisconnected() {
+    this.dispatchEvent(JSONPadRealtime.disconnected);
+  }
+
+  private handleError(message: string) {
+    this.dispatchEvent(new CustomEvent('error', { detail: message }));
+  }
+
+  private handleEvent(messageType: MessageType, data: string) {
+    let parsedData: any;
+    try {
+      parsedData = JSON.parse(data);
+    } catch (error) {
+      this.handleError('Failed to parse data');
+      return;
+    }
+
+    this.dispatchEvent(new CustomEvent(messageType, { detail: parsedData }));
+  }
+}

package/src/types/event-type.ts

@@ -0,0 +1,8 @@
+export type EventType =
+  | 'list-created'
+  | 'list-updated'
+  | 'list-deleted'
+  | 'item-created'
+  | 'item-updated'
+  | 'item-restored'
+  | 'item-deleted';

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './event-type';
+export * from './message-type';

package/src/types/message-type.ts

@@ -0,0 +1,9 @@
+export type MessageType =
+  | 'error'
+  | 'list-created'
+  | 'list-updated'
+  | 'list-deleted'
+  | 'item-created'
+  | 'item-updated'
+  | 'item-restored'
+  | 'item-deleted';

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "target": "es2019",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowJs": false,
+    "declaration": true,
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "esModuleInterop": true,
+    "inlineSourceMap": true,
+  },
+  "include": ["src/**/*"]
+}