@arnek/arnekellmann-sdk 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# Arne Kellmann JavaScript / TypeScript SDK and CLI
+
+JavaScript / TypeScript package for the anonymous, read-only consulting services API.
+SDK integration source is distributed separately from the
+private website repository at [arnekellmann-agent-tools](https://github.com/ArneFfm/arnekellmann-agent-tools).
+No open-source license has been granted.
+
+Requires Node.js 20 or later:
+
+```sh
+npm install @arnek/arnekellmann-sdk
+npx arnekellmann --help
+npx arnekellmann services de
+```
+
+```ts
+import { ArneKellmannClient, ServicesApiError } from '@arnek/arnekellmann-sdk';
+
+try {
+  const catalog = await new ArneKellmannClient().listServices('en');
+  console.log(catalog.services);
+} catch (error) {
+  if (error instanceof ServicesApiError) {
+    console.error(error.status, error.retryAfter);
+  }
+  throw error;
+}
+```
+
+`listServices(language = 'en')` accepts `en` or `de` and returns the complete
+catalog: `language`, `services` (`id`, `name`, `description`, `url`), `pricing`
+(custom quote, no published rates), and `contactUrl`. TypeScript declarations
+are included. No pagination is needed for this small catalog.
+
+CLI output is JSON on stdout; failures go to stderr with exit code 1. `--help`
+and `--version` work offline. To use a local development server:
+
+```sh
+npx arnekellmann services en --base-url http://localhost:4321
+```
+
+The constructor accepts the same HTTP(S) base URL; API paths resolve from its
+origin. URLs containing credentials are rejected. Requests send
+`Accept: application/json`, time out after ten seconds, and are never retried
+automatically. HTTP errors include `status` and the raw `retryAfter` header
+(seconds or HTTP date, or null). Fetch/network and JSON parsing errors propagate.
+
+There are no credentials, contact submission, booking or payment methods. A
+contact URL is informational; opening it does not send an enquiry.
+
+Package validation: `npm pack --dry-run` from this directory. Installing the
+result of `npm pack` exercises the same CLI and included type declarations.
+
+[API documentation](https://arnekellmann.de/developers) ·
+[OpenAPI](https://arnekellmann.de/api/openapi.json)

package/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { ArneKellmannClient } from './index.js';
+
+const usage = `Usage: arnekellmann services [en|de] [--base-url URL]
+       arnekellmann --help
+       arnekellmann --version
+
+Reads public consulting services as JSON. No credentials or writes.
+Default URL: https://arnekellmann.de. Requests time out after 10 seconds.`;
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+      'base-url': { type: 'string' },
+    },
+  });
+  if (values.help) {
+    console.log(usage);
+  } else if (values.version) {
+    console.log(
+      JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version
+    );
+  } else {
+    const [command, language = 'en', ...extra] = positionals;
+    if (command !== 'services' || extra.length) throw new Error(usage);
+    console.log(
+      JSON.stringify(
+        await new ArneKellmannClient(values['base-url']).listServices(language),
+        null,
+        2
+      )
+    );
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/index.d.ts

@@ -0,0 +1,24 @@
+export type Language = 'en' | 'de';
+export interface Service {
+  id: string;
+  name: string;
+  description: string;
+  url: string;
+}
+export interface ServicesResponse {
+  language: Language;
+  services: Service[];
+  pricing: { type: 'custom_quote'; publishedRates: false; url: string };
+  contactUrl: string;
+}
+export declare class ArneKellmannClient {
+  constructor(baseUrl?: string);
+  baseUrl: URL;
+  listServices(language?: Language): Promise<ServicesResponse>;
+}
+export declare class ServicesApiError extends Error {
+  constructor(status: number, retryAfter?: string | null);
+  status: number;
+  /** Raw Retry-After header, either seconds or an HTTP date; null when absent. */
+  retryAfter: string | null;
+}

package/index.js

@@ -0,0 +1,32 @@
+/** Read-only client. No contact submission or automatic retries. */
+export class ArneKellmannClient {
+  constructor(baseUrl = 'https://arnekellmann.de') {
+    this.baseUrl = new URL(baseUrl);
+    if (
+      !['http:', 'https:'].includes(this.baseUrl.protocol) ||
+      this.baseUrl.username ||
+      this.baseUrl.password
+    ) {
+      throw new Error('Use an HTTP(S) base URL without credentials.');
+    }
+  }
+  async listServices(language = 'en') {
+    if (!['en', 'de'].includes(language)) throw new Error('Use language en or de.');
+    const response = await fetch(new URL(`/api/v1/services?language=${language}`, this.baseUrl), {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(10000),
+    });
+    if (!response.ok)
+      throw new ServicesApiError(response.status, response.headers.get('Retry-After'));
+    return response.json();
+  }
+}
+
+export class ServicesApiError extends Error {
+  constructor(status, retryAfter = null) {
+    super(`Services API returned HTTP ${status}`);
+    this.name = 'ServicesApiError';
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@arnek/arnekellmann-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Read the public Arne Kellmann consulting services API.",
+  "homepage": "https://arnekellmann.de/developers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArneFfm/arnekellmann-agent-tools.git",
+    "directory": "packages/sdk-js"
+  },
+  "exports": {
+    "types": "./index.d.ts",
+    "import": "./index.js"
+  },
+  "bin": {
+    "arnekellmann": "./cli.js"
+  },
+  "files": [
+    "index.js",
+    "cli.js",
+    "README.md",
+    "index.d.ts"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "types": "./index.d.ts",
+  "license": "UNLICENSED",
+  "keywords": [
+    "arnekellmann",
+    "consulting",
+    "sdk",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}