@tailor-platform/sdk 0.0.1 → 0.8.0

package/docs/testing.md

@@ -0,0 +1,298 @@
+# Testing Guide
+
+This guide covers testing patterns for Tailor Platform SDK applications using [Vitest](https://vitest.dev/). For a complete working example with full test code, use:
+
+```bash
+npm create @tailor-platform/sdk <your-project-name> --template testing
+```
+
+## Unit Tests
+
+Unit tests verify resolver logic without requiring deployment.
+
+### Simple Resolver Testing
+
+Test resolvers by directly calling `resolver.body()` with mock inputs.
+
+```typescript
+import { unauthenticatedTailorUser } from "@tailor-platform/sdk";
+import resolver from "../src/resolver/add";
+
+describe("add resolver", () => {
+  test("basic functionality", async () => {
+    const result = await resolver.body({
+      input: { left: 1, right: 2 },
+      user: unauthenticatedTailorUser,
+    });
+    expect(result).toBe(3);
+  });
+});
+```
+
+**Key points:**
+
+- Use `unauthenticatedTailorUser` for testing logic that doesn't depend on user context
+- **Best for:** Calculations, data transformations without database dependencies
+
+### Mock TailorDB Client
+
+Mock the global `tailordb.Client` using `vi.stubGlobal()` to simulate database operations and control responses for each query.
+
+```typescript
+import { unauthenticatedTailorUser } from "@tailor-platform/sdk";
+import resolver from "../src/resolver/incrementUserAge";
+
+describe("incrementUserAge resolver", () => {
+  const mockQueryObject = vi.fn();
+
+  beforeAll(() => {
+    vi.stubGlobal("tailordb", {
+      Client: vi.fn(
+        class {
+          connect = vi.fn();
+          end = vi.fn();
+          queryObject = mockQueryObject;
+        },
+      ),
+    });
+  });
+
+  afterAll(() => {
+    vi.unstubAllGlobals();
+  });
+
+  afterEach(() => {
+    mockQueryObject.mockReset();
+  });
+
+  test("basic functionality", async () => {
+    // Mock database responses for each query in sequence
+    mockQueryObject.mockResolvedValueOnce({}); // Begin transaction
+    mockQueryObject.mockResolvedValueOnce({ rows: [{ age: 30 }] }); // Select
+    mockQueryObject.mockResolvedValueOnce({}); // Update
+    mockQueryObject.mockResolvedValueOnce({}); // Commit
+
+    const result = await resolver.body({
+      input: { email: "test@example.com" },
+      user: unauthenticatedTailorUser,
+    });
+
+    expect(result).toEqual({ oldAge: 30, newAge: 31 });
+    expect(mockQueryObject).toHaveBeenCalledTimes(4);
+  });
+});
+```
+
+**Key points:**
+
+- Control exact database responses (query results, errors)
+- Verify database interaction flow (transactions, queries)
+- Test transaction rollback scenarios
+- **Best for:** Business logic with simple database operations
+
+### Dependency Injection Pattern
+
+Extract database operations into a `DbOperations` interface, allowing business logic to be tested independently from Kysely implementation.
+
+First, structure your resolver to accept database operations:
+
+```typescript
+import { createResolver, t } from "@tailor-platform/sdk";
+import { getDB } from "generated/tailordb";
+
+export interface DbOperations {
+  transaction: (fn: (ops: DbOperations) => Promise<unknown>) => Promise<void>;
+  getUser: (
+    email: string,
+    forUpdate: boolean,
+  ) => Promise<{ email: string; age: number }>;
+  updateUser: (user: { email: string; age: number }) => Promise<void>;
+}
+
+export async function decrementUserAge(
+  email: string,
+  dbOperations: DbOperations,
+): Promise<{ oldAge: number; newAge: number }> {
+  let oldAge: number;
+  let newAge: number;
+
+  await dbOperations.transaction(async (ops) => {
+    const user = await ops.getUser(email, true);
+    oldAge = user.age;
+    newAge = user.age - 1;
+    await ops.updateUser({ ...user, age: newAge });
+  });
+
+  return { oldAge, newAge };
+}
+
+export default createResolver({
+  name: "decrementUserAge",
+  operation: "mutation",
+  input: { email: t.string() },
+  body: async (context) => {
+    const db = getDB("tailordb");
+    const dbOperations = createDbOperations(db);
+    return await decrementUserAge(context.input.email, dbOperations);
+  },
+  output: t.object({ oldAge: t.number(), newAge: t.number() }),
+});
+```
+
+Then test by mocking the interface:
+
+```typescript
+import {
+  DbOperations,
+  decrementUserAge,
+} from "../src/resolver/decrementUserAge";
+
+describe("decrementUserAge resolver", () => {
+  test("basic functionality", async () => {
+    // Mock DbOperations implementation
+    const dbOperations = {
+      transaction: vi.fn(
+        async (fn: (ops: DbOperations) => Promise<unknown>) =>
+          await fn(dbOperations),
+      ),
+      getUser: vi
+        .fn()
+        .mockResolvedValue({ email: "test@example.com", age: 30 }),
+      updateUser: vi.fn(),
+    } as DbOperations;
+
+    const result = await decrementUserAge("test@example.com", dbOperations);
+
+    expect(result).toEqual({ oldAge: 30, newAge: 29 });
+    expect(dbOperations.getUser).toHaveBeenCalledExactlyOnceWith(
+      "test@example.com",
+      true,
+    );
+    expect(dbOperations.updateUser).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({ age: 29 }),
+    );
+  });
+});
+```
+
+**Key points:**
+
+- Test business logic independently from Kysely implementation details
+- Mock high-level operations instead of low-level SQL queries
+- **Best for:** Complex business logic with multiple database operations
+
+## End-to-End (E2E) Tests
+
+E2E tests verify your application works correctly when deployed to Tailor Platform. They test the full stack including GraphQL API, database operations, and authentication.
+
+### Setting Up E2E Tests
+
+**1. Global Setup**
+
+Create a global setup file that retrieves deployment information before running tests:
+
+```typescript
+// e2e/globalSetup.ts
+import { machineUserToken, show } from "@tailor-platform/sdk/cli";
+import type { TestProject } from "vitest/node";
+
+declare module "vitest" {
+  export interface ProvidedContext {
+    url: string;
+    token: string;
+  }
+}
+
+export async function setup(project: TestProject) {
+  const app = await show();
+  const tokens = await machineUserToken({
+    name: "admin",
+  });
+  project.provide("url", app.url);
+  project.provide("token", tokens.accessToken);
+}
+```
+
+**2. Test Files**
+
+Create tests that use injected credentials to send real queries to your deployed application:
+
+```typescript
+// e2e/resolver.test.ts
+import { randomUUID } from "node:crypto";
+import { gql, GraphQLClient } from "graphql-request";
+import { describe, expect, inject, test } from "vitest";
+
+function createGraphQLClient() {
+  const endpoint = new URL("/query", inject("url")).href;
+  return new GraphQLClient(endpoint, {
+    headers: {
+      Authorization: `Bearer ${inject("token")}`,
+    },
+    errorPolicy: "all",
+  });
+}
+
+describe("resolver", () => {
+  const graphQLClient = createGraphQLClient();
+
+  describe("incrementUserAge", () => {
+    const uuid = randomUUID();
+
+    test("prepare data", async () => {
+      const query = gql`
+        mutation {
+          createUser(input: {
+            name: "alice"
+            email: "alice-${uuid}@example.com"
+            age: 30
+          }) {
+            id
+          }
+        }
+      `;
+      const result = await graphQLClient.rawRequest(query);
+      expect(result.errors).toBeUndefined();
+    });
+
+    test("basic functionality", async () => {
+      const query = gql`
+        mutation {
+          incrementUserAge(email: "alice-${uuid}@example.com") {
+            oldAge
+            newAge
+          }
+        }
+      `;
+      const result = await graphQLClient.rawRequest(query);
+      expect(result.errors).toBeUndefined();
+      expect(result.data).toEqual({
+        incrementUserAge: { oldAge: 30, newAge: 31 },
+      });
+    });
+  });
+});
+```
+
+**3. Vitest Configuration**
+
+Configure Vitest to use the global setup:
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["e2e/**/*.test.ts"],
+    globalSetup: ["e2e/globalSetup.ts"],
+  },
+});
+```
+
+**Key points:**
+
+- Tests run against actual deployed application
+- `inject("url")` and `inject("token")` provide deployment credentials automatically
+- Machine user authentication enables API access without manual token management
+- Verify database persistence and API contracts
+- **Best for:** Integration testing, end-to-end API validation

package/package.json

@@ -1,10 +1,89 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @tailor-platform/sdk",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+  "version": "0.8.0",
+  "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
+  "license": "MIT",
+  "main": "./dist/configure/index.mjs",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tailor-platform/sdk.git",
+    "directory": "packages/sdk"
+  },
+  "files": [
+    "dist",
+    "postinstall.mjs",
+    "docs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/configure/index.d.mts",
+      "import": "./dist/configure/index.mjs",
+      "default": "./dist/configure/index.mjs"
+    },
+    "./cli": {
+      "types": "./dist/cli/api.d.mts",
+      "import": "./dist/cli/api.mjs",
+      "default": "./dist/cli/api.mjs"
+    },
+    "./test": {
+      "types": "./dist/utils/test/index.d.mts",
+      "import": "./dist/utils/test/index.mjs",
+      "default": "./dist/utils/test/index.mjs"
+    }
+  },
+  "bin": {
+    "tailor-sdk": "./dist/cli/index.mjs"
+  },
+  "types": "./dist/configure/index.d.mts",
+  "dependencies": {
+    "@bufbuild/protobuf": "2.10.0",
+    "@connectrpc/connect": "2.1.0",
+    "@connectrpc/connect-node": "2.1.0",
+    "@standard-schema/spec": "1.0.0",
+    "@urql/core": "5.2.0",
+    "chalk": "5.6.2",
+    "chokidar": "4.0.3",
+    "citty": "0.1.6",
+    "confbox": "0.2.2",
+    "consola": "3.4.2",
+    "es-toolkit": "1.41.0",
+    "inflection": "3.0.2",
+    "madge": "8.0.0",
+    "multiline-ts": "4.0.1",
+    "open": "10.2.0",
+    "pkg-types": "2.3.0",
+    "rolldown": "1.0.0-beta.41",
+    "smol-toml": "1.4.2",
+    "table": "6.9.0",
+    "ts-cron-validator": "1.1.5",
+    "tsx": "4.20.6",
+    "type-fest": "5.2.0",
+    "uuid": "13.0.0",
+    "xdg-basedir": "5.1.0",
+    "zod": "4.1.12"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.1",
+    "@tailor-platform/function-types": "0.7.2",
+    "@types/madge": "5.0.3",
+    "@types/node": "22.19.0",
+    "eslint": "9.39.1",
+    "globals": "16.5.0",
+    "tsdown": "0.15.6",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.46.3",
+    "vitest": "4.0.8"
+  },
+  "scripts": {
+    "test": "vitest",
+    "build": "tsdown && FORCE_CREATE=1 node postinstall.mjs",
+    "lint": "eslint --cache .",
+    "lint:fix": "eslint --cache . --fix",
+    "typecheck": "tsc --noEmit",
+    "prepublish": "pnpm run build",
+    "postinstall": "node postinstall.mjs"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { register } from "node:module";
+
+const __dirname = import.meta.dirname;
+
+async function install() {
+  const cwd = process.env.INIT_CWD || process.cwd();
+  const forceCreate = process.env.FORCE_CREATE === "1";
+
+  // Skip if running in the tailor-sdk package itself (unless forced)
+  if (
+    !forceCreate &&
+    (cwd === __dirname || cwd === resolve(__dirname, "..", ".."))
+  ) {
+    console.log("⚠️  Skipping postinstall in tailor-sdk package itself");
+    return;
+  }
+
+  console.log("🔧 Initializing Tailor Platform SDK type definitions...");
+
+  // Create plugin-generated.d.ts in the dist directory
+  const distDir = resolve(__dirname, "dist");
+  const pluginTypesPath = resolve(distDir, "plugin-generated.d.ts");
+
+  // Check if dist directory exists
+  if (!existsSync(distDir)) {
+    console.log("⚠️  Dist directory not found, skipping type initialization");
+    return;
+  }
+
+  // Try to find and load the user's tailor.config.ts
+  const configPath = process.env.TAILOR_PLATFORM_SDK_CONFIG_PATH
+    ? resolve(cwd, process.env.TAILOR_PLATFORM_SDK_CONFIG_PATH)
+    : resolve(cwd, "tailor.config.ts");
+
+  if (existsSync(configPath)) {
+    try {
+      const configDir = dirname(configPath);
+      process.chdir(configDir);
+      register("tsx", import.meta.url, { data: {} });
+
+      const { generateUserTypes, loadConfig } = await import(
+        pathToFileURL(resolve(__dirname, "dist", "cli", "api.mjs")).href
+      );
+      const { config } = await loadConfig(configPath);
+      await generateUserTypes(config, configPath);
+    } catch (error) {
+      console.warn("⚠️  Failed to generate types from config:", error.message);
+      // Fall through to create empty type definition
+    }
+  }
+
+  // Create empty type definition file as fallback
+  const initialContent = `// This file is auto-generated by @tailor-platform/sdk
+// Do not edit this file manually
+// Regenerated automatically when running 'tailor-sdk apply' or 'tailor-sdk generate'
+
+declare global {
+  namespace TailorSDK {
+    interface AttributeMap {}
+    interface AttributeList {
+      __tuple: string[];
+    }
+  }
+}
+
+export {};
+`;
+
+  try {
+    mkdirSync(dirname(pluginTypesPath), { recursive: true });
+    writeFileSync(pluginTypesPath, initialContent);
+    console.log("✅ Created initial type definitions");
+  } catch (error) {
+    console.error("❌ Failed to create type definitions:", error.message);
+    // Don't exit with error - this shouldn't break the installation
+  }
+}
+
+// Only run if this is the main module
+if (import.meta.url === new URL(import.meta.url).href) {
+  install();
+}