@tsctl/cli 0.2.0

package/bin/tsctl.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli/index.ts";

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@tsctl/cli",
+  "version": "0.2.0",
+  "description": "Terraform-like CLI for managing Typesense collections, aliases, synonyms, and curations",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "bin": {
+    "tsctl": "bin/tsctl.js"
+  },
+  "files": [
+    "bin/tsctl.js",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build src/cli/index.ts --compile --outfile bin/tsctl",
+    "build:all": "bun run build:linux && bun run build:macos && bun run build:windows",
+    "build:linux": "bun build src/cli/index.ts --compile --target=bun-linux-x64 --outfile bin/tsctl-linux-x64",
+    "build:macos": "bun build src/cli/index.ts --compile --target=bun-darwin-arm64 --outfile bin/tsctl-darwin-arm64",
+    "build:windows": "bun build src/cli/index.ts --compile --target=bun-windows-x64 --outfile bin/tsctl-windows-x64.exe",
+    "dev": "bun run src/cli/index.ts",
+    "start": "bun run src/cli/index.ts",
+    "typecheck": "bun x tsc --noEmit",
+    "test": "bun test"
+  },
+  "keywords": [
+    "typesense",
+    "cli",
+    "infrastructure",
+    "terraform"
+  ],
+  "author": "akshitkrnagpal",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akshitkrnagpal/tsctl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/akshitkrnagpal/tsctl/issues"
+  },
+  "homepage": "https://github.com/akshitkrnagpal/tsctl#readme",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "cosmiconfig": "^9.0.0",
+    "diff": "^5.2.0",
+    "dotenv": "^16.4.5",
+    "ora": "^8.0.1",
+    "typesense": "^3.0.0-2",
+    "yaml": "^2.4.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/diff": "^5.2.1",
+    "@types/node": "^20.14.10",
+    "typescript": "^5.5.3"
+  }
+}

package/src/__tests__/analyticsrules.test.ts

@@ -0,0 +1,303 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { setupClient, cleanupTypesense } from "./setup.js";
+import { getTypesenseVersion } from "./helpers.js";
+import {
+  createAnalyticsRule,
+  getAnalyticsRule,
+  listAnalyticsRules,
+  updateAnalyticsRule,
+  deleteAnalyticsRule,
+  analyticsRuleConfigsEqual,
+} from "../resources/analyticsrule.js";
+import { createCollection } from "../resources/collection.js";
+import type { AnalyticsRuleConfig } from "../types/index.js";
+
+/**
+ * Check if analytics is enabled on the Typesense server
+ */
+async function isAnalyticsEnabled(): Promise<boolean> {
+  try {
+    const { getClient } = await import("../client/index.js");
+    const client = getClient();
+    await client.analytics.rules().retrieve();
+    return true;
+  } catch (error: any) {
+    if (error?.httpStatus === 400 && error?.message?.includes("source")) {
+      return false;
+    }
+    // 404 means analytics endpoint doesn't exist
+    if (error?.httpStatus === 404) {
+      return false;
+    }
+    return true; // Other errors mean analytics exists but had issue
+  }
+}
+
+describe("analytics rules (integration)", () => {
+  let version: number;
+  let analyticsAvailable: boolean;
+
+  beforeEach(async () => {
+    setupClient();
+    await cleanupTypesense();
+    version = await getTypesenseVersion();
+    // Check if analytics is actually enabled by trying to create a test rule
+    analyticsAvailable = false;
+    try {
+      const { getClient } = await import("../client/index.js");
+      // Create temp collections
+      try {
+        await getClient().collections().create({ name: "_analytics_test", fields: [{ name: "q", type: "string" }, { name: "count", type: "int32" }] });
+        await getClient().collections().create({ name: "_analytics_test_src", fields: [{ name: "x", type: "string" }] });
+      } catch { /* may already exist */ }
+      await getClient().analytics.rules().upsert("_analytics_test_rule", {
+        type: "popular_queries",
+        collection: "_analytics_test_src",
+        event_type: "search",
+        params: { destination_collection: "_analytics_test", limit: 10 },
+      } as any);
+      await getClient().analytics.rules("_analytics_test_rule").delete();
+      analyticsAvailable = true;
+    } catch {
+      analyticsAvailable = false;
+    }
+    // Cleanup test collections
+    try {
+      const { getClient } = await import("../client/index.js");
+      await getClient().collections("_analytics_test").delete();
+      await getClient().collections("_analytics_test_src").delete();
+    } catch { /* ignore */ }
+  });
+
+  afterEach(async () => {
+    await cleanupTypesense();
+  });
+
+  test("creates popular_queries analytics rule", async () => {
+    if (version >= 30 || !analyticsAvailable) return;
+    // Create source and destination collections
+    await createCollection({
+      name: "products",
+      fields: [{ name: "title", type: "string" }],
+    });
+    await createCollection({
+      name: "popular_queries",
+      fields: [
+        { name: "q", type: "string" },
+        { name: "count", type: "int32" },
+      ],
+    });
+
+    const rule: AnalyticsRuleConfig = {
+      name: "product-popular-queries",
+      type: "popular_queries",
+      collection: "products",
+      event_type: "search",
+      params: {
+        destination_collection: "popular_queries",
+        limit: 1000,
+      },
+    };
+
+    await createAnalyticsRule(rule);
+    const result = await getAnalyticsRule("product-popular-queries");
+    expect(result).not.toBeNull();
+    expect(result!.name).toBe("product-popular-queries");
+    expect(result!.type).toBe("popular_queries");
+    expect(result!.collection).toBe("products");
+  });
+
+  test("creates nohits_queries analytics rule", async () => {
+    if (version >= 30 || !analyticsAvailable) return;
+    await createCollection({
+      name: "products",
+      fields: [{ name: "title", type: "string" }],
+    });
+    await createCollection({
+      name: "nohits",
+      fields: [
+        { name: "q", type: "string" },
+        { name: "count", type: "int32" },
+      ],
+    });
+
+    const rule: AnalyticsRuleConfig = {
+      name: "product-nohits",
+      type: "nohits_queries",
+      collection: "products",
+      event_type: "search",
+      params: {
+        destination_collection: "nohits",
+        limit: 500,
+      },
+    };
+
+    await createAnalyticsRule(rule);
+    const result = await getAnalyticsRule("product-nohits");
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("nohits_queries");
+  });
+
+  test("creates counter analytics rule", async () => {
+    if (version >= 30 || !analyticsAvailable) return;
+    await createCollection({
+      name: "products",
+      fields: [
+        { name: "title", type: "string" },
+        { name: "click_count", type: "int32" },
+      ],
+    });
+
+    const rule: AnalyticsRuleConfig = {
+      name: "product-clicks",
+      type: "counter",
+      collection: "products",
+      event_type: "click",
+      params: {
+        counter_field: "click_count",
+        weight: 1,
+      },
+    };
+
+    await createAnalyticsRule(rule);
+    const result = await getAnalyticsRule("product-clicks");
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("counter");
+    expect(result!.params?.counter_field).toBe("click_count");
+  });
+
+  test("getAnalyticsRule returns null for non-existent", async () => {
+    const result = await getAnalyticsRule("nonexistent");
+    expect(result).toBeNull();
+  });
+
+  test("listAnalyticsRules returns all rules", async () => {
+    if (version >= 30 || !analyticsAvailable) return;
+    await createCollection({
+      name: "products",
+      fields: [{ name: "title", type: "string" }],
+    });
+    await createCollection({
+      name: "popular_queries",
+      fields: [
+        { name: "q", type: "string" },
+        { name: "count", type: "int32" },
+      ],
+    });
+    await createCollection({
+      name: "nohits",
+      fields: [
+        { name: "q", type: "string" },
+        { name: "count", type: "int32" },
+      ],
+    });
+
+    await createAnalyticsRule({
+      name: "rule1",
+      type: "popular_queries",
+      collection: "products",
+      event_type: "search",
+      params: { destination_collection: "popular_queries" },
+    });
+    await createAnalyticsRule({
+      name: "rule2",
+      type: "nohits_queries",
+      collection: "products",
+      event_type: "search",
+      params: { destination_collection: "nohits" },
+    });
+
+    const rules = await listAnalyticsRules();
+    const names = rules.map((r) => r.name);
+    expect(names).toContain("rule1");
+    expect(names).toContain("rule2");
+  });
+
+  test("deleteAnalyticsRule removes rule", async () => {
+    if (version >= 30 || !analyticsAvailable) return;
+    await createCollection({
+      name: "products",
+      fields: [{ name: "title", type: "string" }],
+    });
+    await createCollection({
+      name: "popular",
+      fields: [
+        { name: "q", type: "string" },
+        { name: "count", type: "int32" },
+      ],
+    });
+
+    await createAnalyticsRule({
+      name: "to-delete",
+      type: "popular_queries",
+      collection: "products",
+      event_type: "search",
+      params: { destination_collection: "popular" },
+    });
+
+    await deleteAnalyticsRule("to-delete");
+    const result = await getAnalyticsRule("to-delete");
+    expect(result).toBeNull();
+  });
+
+  test("updateAnalyticsRule modifies rule", async () => {
+    if (version >= 30 || !analyticsAvailable) return;
+    await createCollection({
+      name: "products",
+      fields: [{ name: "title", type: "string" }],
+    });
+    await createCollection({
+      name: "popular",
+      fields: [
+        { name: "q", type: "string" },
+        { name: "count", type: "int32" },
+      ],
+    });
+
+    await createAnalyticsRule({
+      name: "my-rule",
+      type: "popular_queries",
+      collection: "products",
+      event_type: "search",
+      params: { destination_collection: "popular", limit: 100 },
+    });
+
+    await updateAnalyticsRule({
+      name: "my-rule",
+      type: "popular_queries",
+      collection: "products",
+      event_type: "search",
+      params: { destination_collection: "popular", limit: 500 },
+    });
+
+    const result = await getAnalyticsRule("my-rule");
+    expect(result!.params?.limit).toBe(500);
+  });
+
+  test("analyticsRuleConfigsEqual with matching params", () => {
+    const a: AnalyticsRuleConfig = {
+      name: "rule",
+      type: "popular_queries",
+      collection: "products",
+      event_type: "search",
+      params: { limit: 100 },
+    };
+    const b = { ...a };
+    expect(analyticsRuleConfigsEqual(a, b)).toBe(true);
+  });
+
+  test("analyticsRuleConfigsEqual with different params", () => {
+    const a: AnalyticsRuleConfig = {
+      name: "rule",
+      type: "popular_queries",
+      collection: "products",
+      event_type: "search",
+      params: { limit: 100 },
+    };
+    const b: AnalyticsRuleConfig = {
+      ...a,
+      params: { limit: 200 },
+    };
+    expect(analyticsRuleConfigsEqual(a, b)).toBe(false);
+  });
+});

package/src/__tests__/apikeys.test.ts

@@ -0,0 +1,223 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { setupClient, cleanupTypesense } from "./setup.js";
+import {
+  createApiKey,
+  getApiKey,
+  getApiKeyById,
+  listApiKeys,
+  deleteApiKey,
+  deleteApiKeyByDescription,
+  apiKeyConfigsEqual,
+} from "../resources/apikey.js";
+
+describe("API keys (integration)", () => {
+  beforeEach(async () => {
+    setupClient();
+    await cleanupTypesense();
+  });
+
+  afterEach(async () => {
+    await cleanupTypesense();
+  });
+
+  test("creates search-only key", async () => {
+    const result = await createApiKey({
+      description: "Search-only key for frontend",
+      actions: ["documents:search"],
+      collections: ["products"],
+    });
+
+    expect(result.id).toBeGreaterThanOrEqual(0);
+    expect(result.value).toBeTruthy();
+    expect(result.value.length).toBeGreaterThan(10);
+  });
+
+  test("creates admin key", async () => {
+    const result = await createApiKey({
+      description: "Admin key",
+      actions: ["*"],
+      collections: ["*"],
+    });
+
+    expect(result.id).toBeGreaterThanOrEqual(0);
+  });
+
+  test("creates key with custom value", async () => {
+    const result = await createApiKey({
+      description: "Custom value key",
+      actions: ["documents:search"],
+      collections: ["*"],
+      value: "my-custom-api-key-value-12345678",
+    });
+
+    expect(result.value).toBe("my-custom-api-key-value-12345678");
+  });
+
+  test("creates key with expiration", async () => {
+    const expiresAt = Math.floor(Date.now() / 1000) + 86400; // 24h from now
+    const result = await createApiKey({
+      description: "Expiring key",
+      actions: ["documents:search"],
+      collections: ["*"],
+      expires_at: expiresAt,
+    });
+
+    const retrieved = await getApiKey("Expiring key");
+    expect(retrieved).not.toBeNull();
+    expect(retrieved!.expires_at).toBe(expiresAt);
+  });
+
+  test("getApiKeyById retrieves key", async () => {
+    const created = await createApiKey({
+      description: "Test key by ID",
+      actions: ["documents:search"],
+      collections: ["*"],
+    });
+
+    const retrieved = await getApiKeyById(created.id);
+    expect(retrieved).not.toBeNull();
+    expect(retrieved!.id).toBe(created.id);
+    expect(retrieved!.description).toBe("Test key by ID");
+  });
+
+  test("getApiKeyById returns null for non-existent", async () => {
+    const result = await getApiKeyById(99999);
+    expect(result).toBeNull();
+  });
+
+  test("listApiKeys returns keys with descriptions", async () => {
+    await createApiKey({
+      description: "Key A",
+      actions: ["documents:search"],
+      collections: ["*"],
+    });
+    await createApiKey({
+      description: "Key B",
+      actions: ["*"],
+      collections: ["*"],
+    });
+
+    const keys = await listApiKeys();
+    const descriptions = keys.map((k) => k.description);
+    expect(descriptions).toContain("Key A");
+    expect(descriptions).toContain("Key B");
+  });
+
+  test("deleteApiKey removes by ID", async () => {
+    const created = await createApiKey({
+      description: "To delete by ID",
+      actions: ["*"],
+      collections: ["*"],
+    });
+
+    await deleteApiKey(created.id);
+    const result = await getApiKeyById(created.id);
+    expect(result).toBeNull();
+  });
+
+  test("deleteApiKeyByDescription removes by description", async () => {
+    await createApiKey({
+      description: "To delete by desc",
+      actions: ["*"],
+      collections: ["*"],
+    });
+
+    await deleteApiKeyByDescription("To delete by desc");
+    const result = await getApiKey("To delete by desc");
+    expect(result).toBeNull();
+  });
+
+  test("deleteApiKeyByDescription does nothing for non-existent", async () => {
+    // Should not throw
+    await deleteApiKeyByDescription("nonexistent");
+  });
+
+  test("apiKeyConfigsEqual handles set-like comparison", () => {
+    expect(
+      apiKeyConfigsEqual(
+        {
+          description: "key",
+          actions: ["documents:search", "documents:get"],
+          collections: ["products", "users"],
+        },
+        {
+          description: "key",
+          actions: ["documents:get", "documents:search"],
+          collections: ["users", "products"],
+        }
+      )
+    ).toBe(true);
+  });
+
+  test("apiKeyConfigsEqual detects action differences", () => {
+    expect(
+      apiKeyConfigsEqual(
+        {
+          description: "key",
+          actions: ["documents:search"],
+          collections: ["*"],
+        },
+        {
+          description: "key",
+          actions: ["documents:search", "documents:get"],
+          collections: ["*"],
+        }
+      )
+    ).toBe(false);
+  });
+
+  test("apiKeyConfigsEqual detects collection differences", () => {
+    expect(
+      apiKeyConfigsEqual(
+        {
+          description: "key",
+          actions: ["*"],
+          collections: ["products"],
+        },
+        {
+          description: "key",
+          actions: ["*"],
+          collections: ["products", "users"],
+        }
+      )
+    ).toBe(false);
+  });
+
+  test("apiKeyConfigsEqual considers autodelete", () => {
+    expect(
+      apiKeyConfigsEqual(
+        {
+          description: "key",
+          actions: ["*"],
+          collections: ["*"],
+          autodelete: true,
+        },
+        {
+          description: "key",
+          actions: ["*"],
+          collections: ["*"],
+          autodelete: false,
+        }
+      )
+    ).toBe(false);
+  });
+
+  test("multiple keys with same actions but different descriptions", async () => {
+    await createApiKey({
+      description: "Frontend search",
+      actions: ["documents:search"],
+      collections: ["products"],
+    });
+    await createApiKey({
+      description: "Backend search",
+      actions: ["documents:search"],
+      collections: ["products"],
+    });
+
+    const frontend = await getApiKey("Frontend search");
+    const backend = await getApiKey("Backend search");
+    expect(frontend).not.toBeNull();
+    expect(backend).not.toBeNull();
+    expect(frontend!.id).not.toBe(backend!.id);
+  });
+});