@hasna/connectors 1.3.45 → 1.4.0

package/connectors/zymbly/src/api/client.ts

@@ -0,0 +1,166 @@
+import type {
+  HttpMethod,
+  JsonObject,
+  QueryParams,
+  RequestOptions,
+  ZymblyConfig,
+} from "../types";
+import { ZymblyApiError } from "../types";
+
+const DEFAULT_BASE_URL = "https://api.zymbly.com/v1";
+
+function normalizePath(path: string): string {
+  const trimmed = path.trim();
+  if (!trimmed) {
+    throw new Error("Zymbly API path is required");
+  }
+  if (/^https?:\/\//i.test(trimmed)) {
+    throw new Error("Zymbly API paths must be relative, not absolute URLs");
+  }
+  const normalized = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  if (normalized.split("/").some((part) => part === "..")) {
+    throw new Error("Zymbly API paths cannot contain parent-directory segments");
+  }
+  return normalized;
+}
+
+function encodePath(value: string | number): string {
+  return encodeURIComponent(String(value));
+}
+
+function appendQuery(url: URL, query?: QueryParams): void {
+  if (!query) {
+    return;
+  }
+  for (const [key, value] of Object.entries(query)) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item !== undefined && item !== null) {
+          url.searchParams.append(key, String(item));
+        }
+      }
+      continue;
+    }
+    if (value !== undefined && value !== null) {
+      url.searchParams.set(key, String(value));
+    }
+  }
+}
+
+function parseResponse(text: string, contentType: string | null): unknown {
+  if (!text) {
+    return {};
+  }
+  if (contentType?.includes("json") || text.startsWith("{") || text.startsWith("[")) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { raw: text };
+    }
+  }
+  return text;
+}
+
+function extractErrorMessage(data: unknown, fallback: string): string {
+  if (typeof data === "string" && data.trim()) {
+    return data.slice(0, 500);
+  }
+  if (data && typeof data === "object") {
+    const record = data as Record<string, unknown>;
+    const message = record.message ?? record.error ?? record.detail ?? record.title;
+    if (typeof message === "string" && message.trim()) {
+      return message;
+    }
+  }
+  return fallback;
+}
+
+export class ZymblyClient {
+  private readonly apiKey?: string;
+  private readonly baseUrl: string;
+
+  constructor(config: ZymblyConfig = {}) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  }
+
+  async request<T = unknown>(path: string, options: RequestOptions = {}): Promise<T> {
+    const method = options.method || (options.body ? "POST" : "GET");
+    const url = this.buildUrl(path, options.query);
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      ...options.headers,
+    };
+    const body = this.prepareBody(method, options);
+    if (body !== undefined && !headers["Content-Type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (options.auth !== false) {
+      headers.Authorization = `Bearer ${this.requireApiKey()}`;
+    }
+    const response = await fetch(url.toString(), { method, headers, body });
+    const text = await response.text();
+    const data = parseResponse(text, response.headers.get("content-type"));
+    if (!response.ok) {
+      throw new ZymblyApiError(
+        extractErrorMessage(data, response.statusText || `Zymbly request failed with ${response.status}`),
+        response.status,
+        data,
+      );
+    }
+    return data as T;
+  }
+
+  listWorkOrders<T = unknown>(query?: QueryParams): Promise<T> {
+    return this.request<T>("/work-orders", { query });
+  }
+
+  getWorkOrder<T = unknown>(workOrderId: string): Promise<T> {
+    return this.request<T>(`/work-orders/${encodePath(workOrderId)}`);
+  }
+
+  searchParts<T = unknown>(query?: QueryParams): Promise<T> {
+    return this.request<T>("/parts", { query });
+  }
+
+  createMaintenanceNote<T = unknown>(workOrderId: string, note: string): Promise<T> {
+    return this.request<T>(`/work-orders/${encodePath(workOrderId)}/notes`, {
+      method: "POST",
+      body: { note },
+    });
+  }
+
+  createMaintenanceNoteWithBody<T = unknown>(workOrderId: string, body: JsonObject): Promise<T> {
+    return this.request<T>(`/work-orders/${encodePath(workOrderId)}/notes`, {
+      method: "POST",
+      body,
+    });
+  }
+
+  rawRequest<T = unknown>(method: HttpMethod, path: string, options: Omit<RequestOptions, "method"> = {}): Promise<T> {
+    return this.request<T>(path, { ...options, method });
+  }
+
+  private buildUrl(path: string, query?: QueryParams): URL {
+    const url = new URL(`${this.baseUrl}${normalizePath(path)}`);
+    appendQuery(url, query);
+    return url;
+  }
+
+  private prepareBody(method: HttpMethod, options: RequestOptions): string | undefined {
+    if (method === "GET") {
+      return undefined;
+    }
+    if (options.body === undefined) {
+      return undefined;
+    }
+    return typeof options.body === "string" ? options.body : JSON.stringify(options.body);
+  }
+
+  private requireApiKey(): string {
+    if (!this.apiKey) {
+      throw new Error("Zymbly API key is required. Use config set-key or set ZYMBLY_API_KEY.");
+    }
+    return this.apiKey;
+  }
+}

package/connectors/zymbly/src/api/index.ts

@@ -0,0 +1 @@
+export { ZymblyClient } from "./client";

package/connectors/zymbly/src/cli/index.ts

@@ -0,0 +1,156 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { ZymblyClient } from "../api";
+import type { HttpMethod, JsonObject, JsonValue, OutputFormat, QueryParams, QueryValue } from "../types";
+import {
+  clearConfig,
+  getApiKey,
+  getBaseUrl,
+  getConfigPath,
+  setApiKey,
+  setBaseUrl,
+} from "../utils/config";
+import { error, print, success } from "../utils/output";
+
+const VERSION = "0.0.1";
+const DEFAULT_BASE_URL = "https://api.zymbly.com/v1";
+
+function parseJson(value: string | undefined, label: string): JsonValue {
+  if (!value) {
+    return {};
+  }
+  try {
+    return JSON.parse(value) as JsonValue;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Invalid ${label}: ${message}`);
+  }
+}
+
+function parseObject(value: string | undefined, label: string): JsonObject {
+  const parsed = parseJson(value, label);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object`);
+  }
+  return parsed as JsonObject;
+}
+
+function parseQueryParams(value: string | undefined): QueryParams | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const parsed = parseObject(value, "query");
+  const query: QueryParams = {};
+  for (const [key, entry] of Object.entries(parsed)) {
+    if (Array.isArray(entry)) {
+      query[key] = entry.map((item) => {
+        if (typeof item === "string" || typeof item === "number" || typeof item === "boolean" || item === null || item === undefined) {
+          return item as QueryValue;
+        }
+        throw new Error(`query.${key} must contain only string, number, boolean, null, or undefined values`);
+      });
+      continue;
+    }
+    if (typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean" || entry === null || entry === undefined) {
+      query[key] = entry as QueryValue;
+      continue;
+    }
+    throw new Error(`query.${key} must be a string, number, boolean, null, or an array of those values`);
+  }
+  return query;
+}
+
+function getFormat(command: Command): OutputFormat {
+  return (command.optsWithGlobals().format || "pretty") as OutputFormat;
+}
+
+function getClient(command: Command): ZymblyClient {
+  const options = command.optsWithGlobals();
+  const apiKey = options.apiKey || getApiKey();
+  const baseUrl = options.baseUrl || getBaseUrl();
+  if (!apiKey) {
+    error("No Zymbly API key configured. Use config set-key or set ZYMBLY_API_KEY.");
+    process.exit(1);
+  }
+  return new ZymblyClient({ apiKey, baseUrl });
+}
+
+async function run(command: Command, action: (client: ZymblyClient) => Promise<unknown>): Promise<void> {
+  try {
+    print(await action(getClient(command)), getFormat(command));
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+const program = new Command()
+  .name("connect-zymbly")
+  .description("Zymbly aircraft maintenance API connector")
+  .version(VERSION)
+  .option("-k, --api-key <key>", "Zymbly API key")
+  .option("--base-url <url>", "API base URL", DEFAULT_BASE_URL)
+  .option("-f, --format <format>", "Output format: json or pretty", "pretty");
+
+const config = program.command("config").description("Manage local configuration");
+config.command("set-key <key>").description("Save API key").action((key: string) => {
+  setApiKey(key);
+  success("Zymbly API key saved");
+});
+config.command("set-base-url <url>").description("Save API base URL").action((url: string) => {
+  setBaseUrl(url);
+  success("Zymbly base URL saved");
+});
+config.command("show").description("Show current configuration").action(() => {
+  const key = getApiKey();
+  print({
+    configPath: getConfigPath(),
+    baseUrl: getBaseUrl() || DEFAULT_BASE_URL,
+    apiKey: key ? `${key.slice(0, 6)}...` : null,
+  });
+});
+config.command("clear").description("Clear local configuration").action(() => {
+  clearConfig();
+  success("Zymbly configuration cleared");
+});
+
+const workOrders = program.command("work-orders").description("Manage work orders");
+workOrders
+  .command("list")
+  .description("List work orders")
+  .option("-q, --query <json>", "Query params JSON object")
+  .action((opts, cmd) => run(cmd, (client) => client.listWorkOrders(parseQueryParams(opts.query))));
+workOrders
+  .command("get <workOrderId>")
+  .description("Get a work order by ID")
+  .action((workOrderId: string, _opts, cmd) => run(cmd, (client) => client.getWorkOrder(workOrderId)));
+
+const parts = program.command("parts").description("Search aircraft parts");
+parts
+  .command("search")
+  .description("Search parts catalog")
+  .option("-q, --query <json>", "Query params JSON object")
+  .action((opts, cmd) => run(cmd, (client) => client.searchParts(parseQueryParams(opts.query))));
+
+const notes = program.command("notes").description("Maintenance notes");
+notes
+  .command("create <workOrderId>")
+  .description("Create a maintenance note on a work order")
+  .requiredOption("-n, --note <text>", "Note text")
+  .action((workOrderId: string, opts, cmd) => run(cmd, (client) => client.createMaintenanceNote(workOrderId, opts.note)));
+
+program
+  .command("raw <method> <path>")
+  .description("Call a raw Zymbly API path")
+  .option("-b, --body <json>", "JSON body")
+  .option("-q, --query <json>", "Query params JSON object")
+  .action((method: string, path: string, opts, cmd) =>
+    run(cmd, (client) =>
+      client.rawRequest(method.toUpperCase() as HttpMethod, path, {
+        body: opts.body ? parseJson(opts.body, "body") : undefined,
+        query: parseQueryParams(opts.query),
+      }),
+    ),
+  );
+
+program.parse();

package/connectors/zymbly/src/index.ts

@@ -0,0 +1,12 @@
+export { ZymblyClient } from "./api";
+export type {
+  HttpMethod,
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+  OutputFormat,
+  QueryParams,
+  RequestOptions,
+  ZymblyConfig,
+} from "./types";
+export { ZymblyApiError } from "./types";

package/connectors/zymbly/src/types/index.ts

@@ -0,0 +1,34 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+  [key: string]: JsonValue | undefined;
+}
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type OutputFormat = "json" | "pretty";
+export type QueryValue = string | number | boolean | null | undefined;
+export type QueryParams = Record<string, QueryValue | QueryValue[]>;
+
+export interface ZymblyConfig {
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+export interface RequestOptions {
+  method?: HttpMethod;
+  body?: JsonValue | string;
+  headers?: Record<string, string>;
+  query?: QueryParams;
+  auth?: boolean;
+}
+
+export class ZymblyApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = "ZymblyApiError";
+  }
+}

package/connectors/zymbly/src/utils/config.ts

@@ -0,0 +1,52 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+interface StoredConfig {
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+const CONFIG_PATH = join(homedir(), ".config", "hasna-connectors", "zymbly.json");
+
+function readConfig(): StoredConfig {
+  if (!existsSync(CONFIG_PATH)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8")) as StoredConfig;
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(config: StoredConfig): void {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+export function getConfigPath(): string {
+  return CONFIG_PATH;
+}
+
+export function getApiKey(): string | undefined {
+  return process.env.ZYMBLY_API_KEY || readConfig().apiKey;
+}
+
+export function getBaseUrl(): string | undefined {
+  return process.env.ZYMBLY_BASE_URL || readConfig().baseUrl;
+}
+
+export function setApiKey(apiKey: string): void {
+  writeConfig({ ...readConfig(), apiKey });
+}
+
+export function setBaseUrl(baseUrl: string): void {
+  writeConfig({ ...readConfig(), baseUrl });
+}
+
+export function clearConfig(): void {
+  if (existsSync(CONFIG_PATH)) {
+    rmSync(CONFIG_PATH);
+  }
+}

package/connectors/zymbly/src/utils/output.ts

@@ -0,0 +1,17 @@
+import type { OutputFormat } from "../types";
+
+export function print(data: unknown, format: OutputFormat = "pretty"): void {
+  if (format === "json") {
+    console.log(JSON.stringify(data));
+    return;
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export function error(message: string): void {
+  console.error(message);
+}
+
+export function success(message: string): void {
+  console.log(message);
+}

package/connectors/zymbly/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "skipLibCheck": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"]
+}

package/dist/db/database.d.ts

@@ -1,4 +1,5 @@
-import { SqliteAdapter } from "@hasna/cloud";
+import { SqliteAdapter } from "./sqlite-adapter.js";
+export { SqliteAdapter } from "./sqlite-adapter.js";
 export type Database = SqliteAdapter;
 /**
  * Get the connectors home directory.

package/dist/db/sqlite-adapter.d.ts

@@ -0,0 +1,43 @@
+import { Database as BunDatabase, type SQLQueryBindings, type Statement } from "bun:sqlite";
+/** Result of a mutating statement, mirroring `bun:sqlite`'s `Statement.run()`. */
+export interface RunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+/**
+ * Statement bindings. `bun:sqlite` accepts both the spread form
+ * (`run(sql, a, b)`) and a single array of values (`run(sql, [a, b])`), and
+ * call sites in `src/db` use both, so both are allowed here.
+ */
+export type Bindings = SQLQueryBindings | SQLQueryBindings[];
+/** A prepared statement handle returned by {@link SqliteAdapter.prepare}. */
+export interface PreparedStatement {
+    run(...params: Bindings[]): RunResult;
+    get(...params: Bindings[]): unknown;
+    all(...params: Bindings[]): unknown[];
+    finalize(): void;
+}
+/**
+ * Thin synchronous wrapper over `bun:sqlite`.
+ *
+ * This is the local-only storage engine for the connectors database. It was
+ * previously imported from `@hasna/cloud`, which is retired and unsupported;
+ * the class is kept API-compatible with that import so the rest of `src/db`
+ * and its tests are unchanged.
+ *
+ * Parameters are forwarded to `bun:sqlite` verbatim, so both the spread form
+ * (`run(sql, a, b)`) and the array form (`run(sql, [a, b])`) keep working.
+ */
+export declare class SqliteAdapter {
+    private readonly db;
+    constructor(path: string);
+    run(sql: string, ...params: Bindings[]): RunResult;
+    get(sql: string, ...params: Bindings[]): unknown;
+    all(sql: string, ...params: Bindings[]): unknown[];
+    exec(sql: string): void;
+    query(sql: string): Statement;
+    prepare(sql: string): PreparedStatement;
+    close(): void;
+    transaction<T>(fn: () => T): T;
+    get raw(): BunDatabase;
+}