@itzworking/devkit 0.0.198-canary.20250707-e7f7621

package/dist-es/generate-api-clients/templates/hook-mutation.hbs

@@ -0,0 +1,39 @@
+// prettier-ignore
+/* eslint-disable */
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+{{#each imports}}
+import { {{names}} } from "{{path}}";
+{{/each}}
+
+export const {{hookName}} = () => {
+  const queryClient = useQueryClient();
+  const useMutationResult = useMutation({
+    mutationFn: ({{mutationParams}}){{#if outputType}}: Promise<{{outputType.typeName}}>{{/if}} => {{apiClassName}}.{{actionName}}({{#if mutationParams}}variables{{/if}}),
+    onMutate: async (variables) => {
+      // A mutation is about to happen!
+    },
+    onError: async (err, variables, context) => {
+      // An error happened!
+    },
+    onSuccess: async (data, variables, context) => {
+      // Boom baby!
+    },
+    onSettled: async () => {
+      // Error or success... doesn't matter!
+    }
+  });
+
+  return {
+    {{actionName}}: useMutationResult.mutate,
+    {{actionName}}Async: useMutationResult.mutateAsync,
+    is{{apiClassName}}Error: useMutationResult.isError,
+    is{{apiClassName}}Idle: useMutationResult.isIdle,
+    is{{apiClassName}}Paused: useMutationResult.isPaused,
+    is{{apiClassName}}Pending: useMutationResult.isPending,
+    is{{apiClassName}}Success: useMutationResult.isSuccess,
+    {{actionName}}Status: useMutationResult.status,
+    {{actionName}}Error: useMutationResult.error,
+    reset{{apiClassName}}: useMutationResult.reset
+  };
+};

package/dist-es/generate-api-clients/templates/hook-query.hbs

@@ -0,0 +1,28 @@
+// prettier-ignore
+/* eslint-disable */
+
+import { useQuery } from "@tanstack/react-query";
+{{#each imports}}
+import { {{names}} } from "{{path}}";
+{{/each}}
+
+export const {{relatedDataName}}QueryKey = ({{queryKeyParams}}) => [
+{{{queryKeyArray}}}
+];
+
+export const {{hookName}} = ({{queryKeyParams}}) => {
+  const useQueryResult = useQuery({
+    queryKey: {{relatedDataName}}QueryKey({{queryKeyInput}}),
+    queryFn: (){{#if outputType}}: Promise<{{outputType.typeName}}>{{/if}} => {{apiClassName}}.{{actionName}}({{queryKeyInput}})
+  });
+
+  return {
+    {{relatedDataName}}: useQueryResult.data,
+    {{relatedDataName}}UpdatedAt: useQueryResult.dataUpdatedAt,
+    {{actionName}}Error: useQueryResult.error,
+    is{{actionClassName}}Loading: useQueryResult.isLoading,
+    is{{actionClassName}}Fetching: useQueryResult.isFetching,
+    refetch{{actionClassName}}: useQueryResult.refetch,
+    {{actionName}}Status: useQueryResult.status
+  };
+};

package/dist-es/generate-api-clients/types.js

@@ -0,0 +1 @@
+export {};

package/dist-es/generate-api-clients/utils.js

@@ -0,0 +1,79 @@
+import * as fs from "fs";
+import * as path from "path";
+export const getITzWorkingResources = ({ resourcesFilePath, }) => {
+    if (!fs.existsSync(resourcesFilePath)) {
+        console.error(`${resourcesFilePath} file not found. Please deploy your application.`);
+        process.exit(1);
+    }
+    const data = fs.readFileSync(resourcesFilePath, "utf-8");
+    try {
+        return JSON.parse(data);
+    }
+    catch (e) {
+        console.error(`Error parsing ${resourcesFilePath} file. Please ensure it is a valid JSON file.`);
+        process.exit(1);
+    }
+};
+export const prepareImports = (apis, options) => {
+    const formatedApis = Array.isArray(apis) ? apis : [apis];
+    const imports = [];
+    const importMap = {};
+    if (options.typeResolutionMode === "source-imports") {
+        for (const api of formatedApis) {
+            for (const [importPath, importNames] of Object.entries(api.imports)) {
+                if (!importMap[importPath])
+                    importMap[importPath] = new Set();
+                importNames.forEach((name) => importMap[importPath].add(name));
+            }
+        }
+    }
+    else if (options.typeResolutionMode === "inline-types") {
+        for (const api of formatedApis) {
+            const typeSpecs = [api.inputType, api.outputType];
+            for (const typeSpec of typeSpecs) {
+                if (!typeSpec || !typeSpec.importPath)
+                    continue;
+                if (!importMap["./types"])
+                    importMap["./types"] = new Set();
+                importMap["./types"].add(typeSpec.typeName);
+            }
+        }
+    }
+    else {
+        throw new Error(`Unsupported typeResolutionMode: ${options.typeResolutionMode}.`);
+    }
+    for (const importPath of Object.keys(importMap).sort()) {
+        imports.push({
+            path: importPath,
+            names: Array.from(importMap[importPath]).sort().join(", "),
+        });
+    }
+    return imports.sort((a, b) => b.path.localeCompare(a.path));
+};
+export const toPropertyName = (s) => {
+    return s
+        .replace(/([^a-zA-Z0-9])+(.)?/g, (_, __, chr) => chr ? chr.toUpperCase() : "")
+        .replace(/[^a-zA-Z\d]/g, "")
+        .replace(/^([A-Z])/, (m) => m.toLowerCase());
+};
+export const toClassName = (s) => {
+    const propertyName = toPropertyName(s);
+    return propertyName.charAt(0).toUpperCase() + propertyName.slice(1);
+};
+export const toFileName = (s) => {
+    return s
+        .replace(/([a-z\d])([A-Z])/g, "$1_$2")
+        .toLowerCase()
+        .replace(/(?!^_)[ _]/g, "-");
+};
+export const writeFile = (params) => {
+    const { filePath, content, allowOverwrite } = params;
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    if (fs.existsSync(filePath) && !allowOverwrite) {
+        return;
+    }
+    fs.writeFileSync(filePath, content);
+};

package/dist-es/index.js

@@ -0,0 +1 @@
+export * from "./generate-api-clients";

package/dist-types/generate-api-clients/api-type-spec-utils.d.ts

@@ -0,0 +1,4 @@
+import { APITypeSpec } from "./types";
+import { SourceFile } from "ts-morph";
+export declare const setTypeKind: (type: APITypeSpec | null, sourceFile: SourceFile) => void;
+export declare const extractTypeDefinition: (type: APITypeSpec | null, sourceFile: SourceFile) => void;

package/dist-types/generate-api-clients/copy-api-client.d.ts

@@ -0,0 +1,5 @@
+export declare const copyApiClient: (options: {
+    outputDirectory: string;
+    allowOverwrite: boolean;
+    verbose: boolean;
+}) => void;

package/dist-types/generate-api-clients/generate-api-client-class.d.ts

@@ -0,0 +1,11 @@
+import { APIDetails } from "./types";
+export declare const generateApiClientClass: ({ basePath, apis, }: {
+    basePath: string;
+    apis: APIDetails[];
+}, options: {
+    typeResolutionMode: string;
+    verbose: boolean;
+}) => {
+    apiClientClassFile: string;
+    apiTypesFile: string;
+};

package/dist-types/generate-api-clients/generate-api-clients.d.ts

@@ -0,0 +1,2 @@
+import { APIClientGeneratorOptions } from "./types";
+export declare const generateApiClients: (options?: APIClientGeneratorOptions) => Promise<void>;

package/dist-types/generate-api-clients/generate-hook.d.ts

@@ -0,0 +1,11 @@
+import { APIDetails } from "./types";
+export declare const generateHook: ({ basePath, api, }: {
+    basePath: string;
+    api: APIDetails;
+}, options: {
+    typeResolutionMode: string;
+    verbose: boolean;
+}) => {
+    hookName: string;
+    hookFile: string;
+};

package/dist-types/generate-api-clients/handlebars-helpers.d.ts

@@ -0,0 +1 @@
+export declare const handlebarsHelpers: () => void;

package/dist-types/generate-api-clients/index.d.ts

@@ -0,0 +1 @@
+export * from "./generate-api-clients";

package/dist-types/generate-api-clients/parse-discovered-apis.d.ts

@@ -0,0 +1,8 @@
+import { APIDetails, ITzDiscoveredResources } from "./types";
+export declare const parseDiscoveredApis: (resources: ITzDiscoveredResources, options: {
+    tsConfigPath: string;
+    typeResolutionMode: string;
+    verbose: boolean;
+}) => {
+    [basePath: string]: APIDetails[];
+};

package/dist-types/generate-api-clients/sync-api-clients.d.ts

@@ -0,0 +1 @@
+export declare const syncApiClients: (webappDataPath: string) => void;

package/dist-types/generate-api-clients/template-loader.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Loads a template file from the templates directory.
+ * Works in both development and production environments.
+ */
+export declare function loadTemplate(templateName: string): string;

package/dist-types/generate-api-clients/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Configuration for generating TypeScript API clients and React Query hooks
+ * from discovered AWS Lambda handlers via itzworking deployment resources
+ */
+export interface APIClientGeneratorOptions {
+    /**
+     * Path to the TypeScript configuration file for parsing Lambda handlers
+     * Used to resolve type imports and compile backend code analysis
+     * @default "tsconfig.json"
+     */
+    tsConfigPath?: string;
+    /**
+     * Target type system for generated API clients
+     * Determines how Lambda handler types are transformed for frontend consumption
+     * - "preserve-backend": Maintain the same type system as the backend
+     * - "zod-schema": Convert all types to Zod schemas for runtime validation
+     * - "decorated-class": Convert all types to @itzworking/decorated-class format
+     * @default "preserve-backend"
+     */
+    targetTypeSystem?: "preserve-backend" | "zod-schemas" | "decorated-classes";
+    /**
+     * Strategy for resolving type definitions in generated clients
+     * Controls how backend types are made available to the frontend
+     * - "source-imports": Import types directly from Lambda source files (requires monorepo setup)
+     * - "inline-types": Recreate and embed all type definitions within generated clients
+     * @default "source-imports"
+     */
+    typeResolutionMode?: "source-imports" | "inline-types";
+    /**
+     * Enable detailed logging for debugging and development
+     * Provides comprehensive information about:
+     * - Lambda handler discovery and parsing
+     * - Type resolution and transformation
+     * - File generation and output processes
+     * - Import path resolution
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Allow overwriting existing files in the output directory
+     * When false, generation will fail if target files already exist
+     * Useful for preventing accidental overwrites in production workflows
+     * @default false
+     */
+    allowOverwrite?: boolean;
+    /**
+     * Remove all existing files from output directory before generation
+     * Ensures clean generation and removes any orphaned files
+     * Recommended when API structure changes frequently
+     * @default false
+     */
+    cleanOutputDir?: boolean;
+    /**
+     * Directory path where generated API clients will be written
+     * Should point to your frontend application's API client directory
+     * @default "out/apis"
+     */
+    outputDirectory?: string;
+    /**
+     * Path to the itzworking resources file containing API endpoint mappings
+     * This file is generated by itzworking deployment and contains
+     * the relationship between API routes and Lambda handlers
+     * @default "cdk.itzworking.json"
+     */
+    resourcesFilePath?: string;
+}
+export type Handler = {
+    id: string;
+    folderPath: string;
+    description: string;
+};
+export type APIHandler = Handler & {
+    method: string;
+    authorizerId?: string;
+};
+export type ITzDiscoveredResources = {
+    discoveredResources: {
+        [key: string]: {
+            apis: APIHandler[];
+            events: Handler[];
+            "step-functions": Handler[];
+            handlers: Handler[];
+        };
+    };
+};
+export type APITypeSpec = {
+    typeName: string;
+    importPath: string | null;
+    typeDefinition: {
+        allowedImports: {
+            namespaceImport: boolean;
+            importPath: string;
+            importNames: string[];
+        }[];
+        inlinedFiles: {
+            filePath: string;
+            text: string;
+        }[];
+    };
+    structure: any;
+    kind: "decorated-class" | "zod-schema" | "unknown";
+};
+export type APIDetails = {
+    method: "GET" | "POST" | "PUT" | "DELETE" | string;
+    fullPath: string;
+    actionName: string;
+    relatedDataName: string;
+    inputType: APITypeSpec | null;
+    outputType: APITypeSpec | null;
+    imports: {
+        [path: string]: string[];
+    };
+};

package/dist-types/generate-api-clients/utils.d.ts

@@ -0,0 +1,21 @@
+import { APIDetails, ITzDiscoveredResources } from "./types";
+export declare const getITzWorkingResources: ({ resourcesFilePath, }: {
+    resourcesFilePath: string;
+    verbose: boolean;
+}) => ITzDiscoveredResources;
+export declare const prepareImports: (apis: APIDetails | APIDetails[], options: {
+    typeResolutionMode: string;
+    verbose: boolean;
+}) => {
+    path: string;
+    names: string;
+}[];
+export declare const toPropertyName: (s: string) => string;
+export declare const toClassName: (s: string) => string;
+export declare const toFileName: (s: string) => string;
+export declare const writeFile: (params: {
+    filePath: string;
+    content: string;
+    allowOverwrite: boolean;
+    verbose: boolean;
+}) => void;

package/dist-types/index.d.ts

@@ -0,0 +1 @@
+export * from "./generate-api-clients";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@itzworking/devkit",
+  "version": "0.0.198-canary.20250707-e7f7621",
+  "main": "./dist-cjs/index.js",
+  "module": "./dist-es/index.js",
+  "types": "./dist-types/index.d.ts",
+  "scripts": {
+    "build:all": "concurrently \"npm run build:cjs\" \"npm run build:es\" \"npm run build:types\"",
+    "build:cjs": "tsc -p tsconfig.cjs.json && npm run copy:templates",
+    "build:es": "tsc -p tsconfig.es.json && npm run copy:templates",
+    "build:types": "tsc -p tsconfig.types.json",
+    "copy:templates": "node scripts/copy-templates.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist-*/**",
+    "!**/*.tsbuildinfo"
+  ],
+  "peerDependencies": {
+    "ts-morph": "26.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "homepage": "https://itzworking.io",
+  "nx": {
+    "targets": {
+      "publish": {
+        "dependsOn": [
+          "build:all"
+        ],
+        "executor": "nx:run-commands",
+        "options": {
+          "command": "node scripts/ci/publish.mjs {projectRoot}"
+        }
+      }
+    },
+    "tags": [
+      "type:lib"
+    ]
+  }
+}