Deno

.github/copilot-instructions.md

@@ -0,0 +1,66 @@
+This TypeScript project, built with Deno, is a library for JavaScript developers to consume the
+xMatters API (aka `xmApi`).
+
+### Project Priorities
+
+1. **Good DX**:
+
+- The library should provide a great developer experience (DX) for JavaScript and TypeScript
+  developers who use it (consumers), and for those who develop it (maintainers).
+- When these 2 priorities are at odds, the library should prioritize a good DX for consumers.
+- It should be easy to use, with clear and concise APIs that are intuitive to understand.
+
+2. **Consistency**:
+
+- Code should be consistent in **style**, **structure**, and **behavior**.
+- Follow consistent **naming conventions**, **error handling**, and **response structures**.
+
+3. **Zero Dependencies**:
+
+- Do not use any third-party libraries.
+- Only use Deno’s standard library, and only for **unit testing**.
+
+4. **Dependency Injection**:
+
+- Consumers must be able to inject their own:
+  - HTTP client
+  - Logger
+  - Any other external dependencies when applicable
+
+5. **Type Safety**:
+
+- Use TypeScript features when they add value, not just because you can.
+- Avoid the non-null assertion operator (`!`) entirely.
+- Prefer `null` over `undefined` when explicitly assigning absence of a value.
+
+6. **Documentation**: The library should be well-documented, with clear examples and usage
+   instructions.
+
+### Development Guidelines
+
+It should be extremely easy for the maintainers to add more endpoints in the future. The core logic
+of how a request is built and sent should be abstracted away from the endpoint implementations.
+
+- Do not make changes until you are **95% confident** in what needs to be built.
+- Ask clarifying questions until you reach that level of confidence.
+
+#### The Sandbox
+
+- `/sandbox/index.ts` is for quick prototyping and testing.
+- Though version controlled, this file is **not** part of the library shipped to consumers.
+- Do **not** modify the sandbox unless explicitly instructed.
+- Must be run with:
+
+```bash
+deno task sandbox
+```
+
+#### Unit Tests
+
+- **Never** send real HTTP requests.
+- Use _mocks_ or _stubs_ for all external interactions.
+- Must be run with:
+
+```bash
+deno test
+```

.github/workflows/publishToJsr.yml

@@ -0,0 +1,22 @@
+name: Publish to JSR
+
+on:
+  push:
+    tags:
+      - 'v*' # Triggers on version tags like v0.1.0
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Deno
+        uses: denoland/setup-deno@v1
+        with:
+          deno-version: v2.x
+
+      - name: Publish to JSR
+        run: deno publish

.github/workflows/validation.yml

@@ -0,0 +1,25 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - '**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x # Run with latest stable Deno.
+
+      - run: deno fmt --check
+
+      - run: deno lint
+
+      - run: deno test --coverage=cov/
+
+      # This generates a report from the collected coverage in `deno test --coverage`. It is
+      # stored as a .lcov file which integrates well with services such as Codecov, Coveralls and Travis CI.
+      - run: deno coverage --lcov cov/ > cov.lcov

.gitignore

@@ -1,3 +1,3 @@
-node_modules/
-sandbox/config.json
-sandbox/index.js
+sandbox/.env
+dist/
+node_modules/

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "denoland.vscode-deno",
+    "johanfive.fyi"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,20 @@
+{
+  "[typescript]": {
+    "editor.defaultFormatter": "denoland.vscode-deno",
+    "editor.formatOnSave": true
+  },
+  "[json]": {
+    "editor.defaultFormatter": "denoland.vscode-deno",
+    "editor.formatOnSave": true
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "denoland.vscode-deno",
+    "editor.formatOnSave": true
+  },
+  "[yaml]": {
+    "editor.defaultFormatter": "denoland.vscode-deno",
+    "editor.formatOnSave": true
+  },
+  "deno.enable": true,
+  "deno.lint": true
+}

.vscode/typescript.code-snippets

@@ -0,0 +1,88 @@
+{
+  "xMatters Endpoint Index": {
+    "prefix": "xm-endpoint",
+    "description": "Generate a complete endpoint index.ts file",
+    "body": [
+      "import { ResourceClient } from 'core/resource-client.ts';",
+      "import type {",
+      "  Create${1:Resource},",
+      "  Get${1:Resource}Params,",
+      "  Get${1:Resource}sParams,",
+      "  ${1:Resource},",
+      "  Update${1:Resource},",
+      "} from './types.ts';",
+      "import type { HttpResponse, PaginatedHttpResponse, PaginatedResponse } from 'types/http.ts';",
+      "import type { Options } from 'types/request-building-options.ts';",
+      "import type { RequestHandler } from 'core/request-handler.ts';",
+      "",
+      "/**",
+      " * Provides access to the ${2:${1/(.*)/${1:/downcase}/}}s endpoints of the xMatters API.",
+      " * Use this class to manage ${2:${1/(.*)/${1:/downcase}/}}s, including listing, creating, updating, and deleting ${2:${1/(.*)/${1:/downcase}/}}s.",
+      " */",
+      "export class ${1:Resource}sEndpoint {",
+      "  private readonly http: ResourceClient;",
+      "",
+      "  constructor(http: RequestHandler) {",
+      "    this.http = new ResourceClient(http, '/${3:${1/(.*)/${1:/downcase}/}}s');",
+      "  }",
+      "",
+      "  /**",
+      "   * Get a list of ${2:${1/(.*)/${1:/downcase}/}}s from xMatters.",
+      "   * The results can be filtered and paginated using the options object.",
+      "   *",
+      "   * @param options Optional parameters including query filters, headers, and other request options",
+      "   * @returns The HTTP response containing a paginated list of ${2:${1/(.*)/${1:/downcase}/}}s",
+      "   * @throws {XmApiError} If the request fails",
+      "   */",
+      "  get(",
+      "    options?: Options & { query?: Get${1:Resource}sParams },",
+      "  ): Promise<PaginatedHttpResponse<${1:Resource}>> {",
+      "    return this.http.get<PaginatedResponse<${1:Resource}>>(options);",
+      "  }",
+      "",
+      "  /**",
+      "   * Get a ${2:${1/(.*)/${1:/downcase}/}} by its ID or targetName.",
+      "   *",
+      "   * @param identifier The ID or targetName of the ${2:${1/(.*)/${1:/downcase}/}} to retrieve",
+      "   * @param options Optional request options including embed parameters and headers",
+      "   * @returns The HTTP response containing the ${2:${1/(.*)/${1:/downcase}/}}",
+      "   * @throws {XmApiError} If the request fails",
+      "   */",
+      "  getByIdentifier(",
+      "    identifier: string,",
+      "    options?: Options & { query?: Get${1:Resource}Params },",
+      "  ): Promise<HttpResponse<${1:Resource}>> {",
+      "    return this.http.get<${1:Resource}>({ ...options, path: identifier });",
+      "  }",
+      "",
+      "  /**",
+      "   * Create a new ${2:${1/(.*)/${1:/downcase}/}} or update an existing one",
+      "   *",
+      "   * @param ${2:${1/(.*)/${1:/downcase}/}} The ${2:${1/(.*)/${1:/downcase}/}} to create or update",
+      "   * @param options Optional request options such as custom headers",
+      "   * @returns The HTTP response containing the created or updated ${2:${1/(.*)/${1:/downcase}/}}",
+      "   * @throws {XmApiError} If the request fails",
+      "   */",
+      "  save(",
+      "    ${2:${1/(.*)/${1:/downcase}/}}: Create${1:Resource} | Update${1:Resource},",
+      "    options?: Options,",
+      "  ): Promise<HttpResponse<${1:Resource}>> {",
+      "    return this.http.post<${1:Resource}>({ ...options, body: ${2:${1/(.*)/${1:/downcase}/}} });",
+      "  }",
+      "",
+      "  /**",
+      "   * Delete a ${2:${1/(.*)/${1:/downcase}/}} by ID",
+      "   *",
+      "   * @param id The ID of the ${2:${1/(.*)/${1:/downcase}/}} to delete",
+      "   * @param options Optional request options such as custom headers",
+      "   * @returns The HTTP response",
+      "   * @throws {XmApiError} If the request fails",
+      "   */",
+      "  delete(id: string, options?: Options): Promise<HttpResponse<${1:Resource}>> {",
+      "    return this.http.delete<${1:Resource}>({ ...options, path: id });",
+      "  }",
+      "}",
+      "$0"
+    ]
+  }
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 J. Friedrich
+
+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.