`ptkl generate-types`

Fetch IDL definitions from the platform and emit a TypeScript module-augmentation .d.ts file that gives your project typed component models, component functions, and platform functions.

Overview

By default, the SDK's Component and platform function APIs are untyped — field access returns any and function signatures have no compile-time constraints. Once you have defined an IDL on your components and functions, running ptkl generate-types produces a .d.ts file that augments the @ptkl/sdk module with your project-specific types.

After generating, every SDK call is fully typed — autocomplete, compile-time field checks, and typed function inputs/outputs work automatically with no extra imports or wrappers.

Usage

ptkl generate-types [options]

Options

Option	Description
`--output <path>`	Path where the `.d.ts` file will be written (default: `./types/ptkl.d.ts`)
`--env <env>`	Environment to fetch IDL from (uses current profile default when omitted)

Example

ptkl generate-types --output ./types/ptkl.d.ts

How It Works

The command fetches the full IDL from the platform via POST /v1/system/idl and emits a single .d.ts file containing three interfaces:

Interface	Purpose
`ComponentModels`	Typed field shapes for each component, including extension fields and relation expansions
`ComponentFunctions`	Typed `input` / `output` signatures for each component function
`PlatformFunctions`	Typed `input` / `output` signatures for each platform function

These interfaces are injected into the SDK via TypeScript module augmentation — the SDK's open interfaces (ComponentModels, ComponentFunctions, PlatformFunctions) are extended with your project-specific types. No wrapper or factory is needed.

Generated File

// types/ptkl.d.ts — generated by ptkl, do not edit manually

import "@ptkl/sdk";
import "@ptkl/sdk/beta";

interface _CM {
  "customer": {
    name?: string;
    email: string;
    extensions: {
      crm: {
        score?: number;
        notes?: string;
      };
    };
  };
  "order": {
    customer?: string;             // relation field — stores UUID
    customer_RefObj?: {            // hydrated relation object
      name?: string;
      email: string;
    };
    total?: number;
  };
}

interface _CF {
  "customer": {
    "calculateScore": {
      input: { customerId?: string };
      output: number;
    };
  };
}

interface _PF {
  "sendEmail": {
    input: { to?: string; subject?: string; body?: string };
    output: { success?: boolean };
  };
}

declare module "@ptkl/sdk" {
  interface ComponentModels extends _CM {}
  interface ComponentFunctions extends _CF {}
  interface PlatformFunctions extends _PF {}
}

declare module "@ptkl/sdk/beta" {
  interface ComponentModels extends _CM {}
  interface ComponentFunctions extends _CF {}
  interface PlatformFunctions extends _PF {}
}

The generated file augments both @ptkl/sdk and @ptkl/sdk/beta so types work regardless of which import path you use.

Using Typed APIs

Once the .d.ts file is included in your project, SDK calls are automatically typed — no additional imports or wrappers are required:

import { Component } from "@ptkl/sdk"

// Component models — typed fields
const order = Component.factory("order")
const record = await order.findOne({ _id: "abc" })
record.total           // ✓ number
record.customer        // ✓ string (relation UUID)
record.customer_RefObj // ✓ { name?: string; email: string } (hydrated)

// Component functions — typed input and output
const result = await order.function("calculateTotal", {
  items: [{ sku: "ABC", quantity: 2, price: 49.99 }]
})
result.total           // ✓ number

Relation Fields

IDL fields of type relation produce two properties on the generated model:

Property	Type	Description
`field`	`string`	The relation UUID
`field_RefObj`	`T` or `Array<T>`	The hydrated relation object(s), based on cardinality

Including the Generated File

Add the generated file to your TypeScript project in one of two ways:

tsconfig.json includeTriple-slash reference

{
  "include": ["src", "types/ptkl.d.ts"]
}

/// <reference path="../types/ptkl.d.ts" />

Keeping Types in Sync

Re-run generate-types after any IDL change:

ptkl generate-types

The generated file can be committed to your repository — it reflects the current state of your project's component and function IDLs.

Relation to Editor Type Safety

generate-types and editor type safety are separate mechanisms serving different contexts:

Context	How types are provided
Expression editor inside the dashboard	IDL is converted to ambient `.d.ts` declarations and injected into Monaco automatically on load — no command needed
Your own TypeScript project	Run `ptkl generate-types` to produce a module-augmentation `.d.ts` that extends `@ptkl/sdk` interfaces

Both derive from the same IDL. See IDL — Interface Definition Language for how to define field and function types on a component.

ptkl generate-types