trunks

English | 日本語

A CLI wrapper for @kintone/dts-gen that generates TypeScript type definitions for multiple Kintone apps with a single configuration file.

Features

• Generate type definitions for multiple apps in one command
• TypeScript configuration file with type safety (trunks.config.ts)
• Multiple authentication methods (Password, API Token, OAuth)
• Optional Prettier formatting for generated files
• Support for preview environments and guest spaces

Quick Start

Using init command

npx @goqoo/trunks init

This will interactively create a trunks.config.ts file.

Manual setup

1. Create a configuration file trunks.config.ts in your project root:

import { defineConfig } from '@goqoo/trunks';

export default defineConfig({
  host: 'your-subdomain.cybozu.com',
  apps: {
    customer: 123,
    order: 456,
    product: 789,
  },
  auth: { type: 'oauth' },
});

2. Run the command:

With global installation:

npm install -g @goqoo/trunks
trunks

Without global installation:

npx @goqoo/trunks

3. Type definition files will be generated in the dts/ directory:
   • dts/customer-fields.d.ts
   • dts/order-fields.d.ts
   • dts/product-fields.d.ts

Configuration

Basic Configuration

import { defineConfig } from '@goqoo/trunks';

export default defineConfig({
  // Required
  host: 'your-subdomain.cybozu.com',
  apps: {
    customer: 123,  // { appName: appId }
    order: 456,
  },
  auth: { type: 'oauth' },

  // Optional
  outDir: 'dts',           // Output directory (default: "dts")
  preview: false,          // Use preview environment (default: false)
  guestSpaceId: 5,         // Guest space ID (if applicable)
  namespace: 'kintone.types', // TypeScript namespace (default: "kintone.types")
  format: true,            // Format with Prettier (default: false)
});

Authentication Methods

Environment variables can be set in a .env file in your project root:

# .env
KINTONE_USERNAME=your-username
KINTONE_PASSWORD=your-password
KINTONE_API_TOKEN=your-api-token

Warning: If you write credentials directly in the config file, make sure to add the config file to .gitignore to avoid committing sensitive information to version control. Using environment variables (.env file) or stdin prompts is recommended.

Password

Credentials are read from the config file, environment variables KINTONE_USERNAME and KINTONE_PASSWORD, or prompted via stdin (in that order of priority).

auth: { type: 'password' },
// Or with direct credentials (not recommended)
auth: { type: 'password', username: 'user', password: 'pass' },

API Token

Token is read from the config file, environment variable KINTONE_API_TOKEN, or prompted via stdin (in that order of priority).

auth: { type: 'api-token' },
// Or with direct token (not recommended)
auth: { type: 'api-token', token: 'your-token' },

For multiple apps, use comma-separated tokens in .env:

KINTONE_API_TOKEN=token1,token2,token3

OAuth

Uses Gyuma for OAuth authentication. A browser window will open for authentication.

auth: {
  type: 'oauth',
  scope: 'k:app_settings:read',  // Optional: custom scope
},

Additional Options

Basic Authentication

For environments that require basic authentication:

basicAuth: {
  username: 'basic-user',
  password: 'basic-password',
},

Proxy

proxy: {
  host: 'proxy.example.com',
  port: 8080,
},

Client Certificate (for OAuth)

pfx: {
  filepath: '/path/to/cert.pfx',
  password: 'certificate-password',
},

CLI

Options

trunks [options]

Options:
  -c, --config <path>               Path to config file
  -H, --host <host>                 Kintone host (e.g., example.cybozu.com)
  -a, --app <name:id>               App to generate (can be repeated)
  -A, --auth-type <type>            Auth type: password, api-token, oauth
  -u, --username <username>         Kintone username (for password auth)
  -p, --password <password>         Kintone password (for password auth)
  -t, --api-token <token>           Kintone API token (for api-token auth)
  --oauth-scope <scope>             OAuth scope (for oauth auth)
  -o, --out-dir <dir>               Output directory
  --preview                         Use preview environment
  -g, --guest-space-id <id>         Guest space ID
  -n, --namespace <namespace>       TypeScript namespace
  -f, --format                      Format output with Prettier
  --proxy <host:port>               Proxy server
  --basic-auth-username <username>  Basic auth username
  --basic-auth-password <password>  Basic auth password
  -h, --help                        Display help
  -V, --version                     Display version

One-liner execution

You can run without a config file by passing all options via CLI:

npx @goqoo/trunks \
  -H example.cybozu.com \
  -a customer:123 \
  -a order:456 \
  -A api-token \
  -t "$KINTONE_API_TOKEN"

Generated Output

For an app named customer (ID: 123), the following file is generated:

// dts/customer-fields.d.ts
declare namespace kintone.types {
  interface CustomerFields {
    companyName: kintone.fieldTypes.SingleLineText;
    email: kintone.fieldTypes.Link;
    // ...
  }
  interface SavedCustomerFields extends CustomerFields {
    $id: kintone.fieldTypes.Id;
    $revision: kintone.fieldTypes.Revision;
    // ...
  }
}

Development

# Build
yarn build

# Test
yarn test

# Watch mode
yarn dev

Related Projects

• @kintone/dts-gen - The underlying type definition generator
• Gyuma - OAuth authentication for Kintone
• gotenks - Convert kintone TypeScript types to Go types

License

MIT License - see LICENSE for details.