@auxx/sdk 0.0.13 → 0.0.15

package/lib/api/api.js

@@ -123,7 +123,7 @@ class ApiImpl {
         }
         return complete(result.value);
     }
-    async createDeployment({ appId, clientBundleSha, serverBundleSha, deploymentType, settingsSchema, catalog, targetOrganizationId, environmentVariables, version, metadata, }) {
+    async createDeployment({ appId, clientBundleSha, serverBundleSha, deploymentType, settingsSchema, catalog, targetOrganizationId, environmentVariables, version, metadata, publish, }) {
         const result = await this.fetcher.post({
             path: `/api/v1/apps/${appId}/deployments`,
             body: {
@@ -136,6 +136,7 @@ class ApiImpl {
                 environmentVariables,
                 version,
                 metadata,
+                publish,
             },
             schema: createDeploymentResponseSchema,
         });

package/lib/api/schemas.js

@@ -69,6 +69,9 @@ export const confirmBundlesResponseSchema = z.object({
 export const createDeploymentResponseSchema = z.object({
     deploymentId: z.string(),
     version: z.string().nullable(),
+    status: z.string().optional(),
+    publishError: z.string().optional(),
+    unchanged: z.boolean().optional(),
 });
 export const deploymentSchema = z.object({
     id: z.string(),

package/lib/auth/auth.js

@@ -14,6 +14,9 @@ class Authenticator {
     isRefreshingToken = false;
     refreshTimeout = null;
     async ensureAuthed() {
+        if (process.env.AUXX_API_KEY) {
+            return { success: true, value: process.env.AUXX_API_KEY };
+        }
         const existingTokenResult = await getKeychain().load();
         if (isError(existingTokenResult)) {
             return this.promptToAuthenticate();

package/lib/commands/build/validate-typescript.js

@@ -1,6 +1,11 @@
+import chalk from 'chalk';
 import path from 'path';
-import { complete, errored } from '../../errors.js';
-import { getDiagnostics, readConfig, typeScriptErrorSchema } from '../../util/typescript.js';
+import { complete, errored, isErrored } from '../../errors.js';
+import { ensureAppFieldsTypes } from '../../util/ensure-app-fields-types.js';
+import { generateAppEnvTypes } from '../../util/generate-app-env-types.js';
+import { hardExit } from '../../util/hard-exit.js';
+import { spinnerify } from '../../util/spinner.js';
+import { getDiagnostics, printTsError, readConfig, typeScriptErrorSchema, } from '../../util/typescript.js';
 export async function validateTypeScript() {
     try {
         const program = await readConfig(path.resolve('tsconfig.json'));
@@ -22,3 +27,29 @@ export async function validateTypeScript() {
         return errored({ code: 'FILE_SYSTEM_ERROR', error });
     }
 }
+export async function validateTypeScriptOrExit() {
+    const appEnvTypesResult = await generateAppEnvTypes();
+    if (isErrored(appEnvTypesResult)) {
+        process.stderr.write(chalk.yellow(`⚠ Could not generate src/auxx-env.d.ts at ${appEnvTypesResult.error.path}. TypeScript image imports may show warnings.\n`));
+    }
+    else if (appEnvTypesResult.value === 'skipped_unmanaged') {
+        process.stderr.write(chalk.yellow('⚠ Skipping src/auxx-env.d.ts generation because the existing file is unmanaged.\n'));
+    }
+    await ensureAppFieldsTypes();
+    const tsResult = await spinnerify('Validating TypeScript...', 'TypeScript validation passed', validateTypeScript);
+    if (isErrored(tsResult)) {
+        if (tsResult.error.code === 'VALIDATE_TYPE_SCRIPT_ERROR') {
+            process.stdout.write('\n');
+            process.stderr.write(chalk.red(`✖ Found ${tsResult.error.errors.length} TypeScript error(s):\n`));
+            const errorsToShow = tsResult.error.errors.slice(0, 10);
+            for (const error of errorsToShow) {
+                printTsError(error);
+            }
+            if (tsResult.error.errors.length > 10) {
+                process.stderr.write(chalk.yellow(`\n  ... and ${tsResult.error.errors.length - 10} more error(s)\n`));
+            }
+            process.exit(1);
+        }
+        hardExit(`TypeScript validation failed: ${tsResult.error.error}`);
+    }
+}

package/lib/commands/build.js

@@ -2,12 +2,11 @@ import chalk from 'chalk';
 import { Command } from 'commander';
 import { isErrored } from '../errors.js';
 import { ensureAppEntryPoint } from '../util/ensure-app-entry-point.js';
-import { printJsError, printTsError } from '../util/error-reporting.js';
-import { generateAppEnvTypes } from '../util/generate-app-env-types.js';
+import { printJsError } from '../util/error-reporting.js';
 import { hardExit } from '../util/hard-exit.js';
 import { spinnerify } from '../util/spinner.js';
 import { buildJavaScript } from './build/build-javascript.js';
-import { validateTypeScript } from './build/validate-typescript.js';
+import { validateTypeScriptOrExit } from './build/validate-typescript.js';
 export const build = new Command('build')
     .description('Build your Auxx app for production')
     .action(async () => {
@@ -17,29 +16,7 @@ export const build = new Command('build')
             hardExit(`Could not find app entry point at ${entryPointResult.error}\n` +
                 `  Make sure you have a src/index.ts file in your project.`);
         }
-        const appEnvTypesResult = await generateAppEnvTypes();
-        if (isErrored(appEnvTypesResult)) {
-            process.stderr.write(chalk.yellow(`⚠ Could not generate src/auxx-env.d.ts at ${appEnvTypesResult.error.path}. TypeScript image imports may show warnings.\n`));
-        }
-        else if (appEnvTypesResult.value === 'skipped_unmanaged') {
-            process.stderr.write(chalk.yellow('⚠ Skipping src/auxx-env.d.ts generation because the existing file is unmanaged.\n'));
-        }
-        const tsResult = await spinnerify('Validating TypeScript...', 'TypeScript validation passed', validateTypeScript);
-        if (isErrored(tsResult)) {
-            if (tsResult.error.code === 'VALIDATE_TYPESCRIPT_ERROR') {
-                process.stdout.write('\n');
-                process.stderr.write(chalk.red(`✖ Found ${tsResult.error.errors.length} TypeScript error(s):\n`));
-                const errorsToShow = tsResult.error.errors.slice(0, 10);
-                for (const error of errorsToShow) {
-                    await printTsError(error);
-                }
-                if (tsResult.error.errors.length > 10) {
-                    process.stderr.write(chalk.yellow(`\n  ... and ${tsResult.error.errors.length - 10} more error(s)\n`));
-                }
-                process.exit(1);
-            }
-            hardExit('TypeScript validation failed: ' + tsResult.error.error.message);
-        }
+        await validateTypeScriptOrExit();
         const buildResult = await spinnerify('Building JavaScript...', 'JavaScript build completed', buildJavaScript);
         if (isErrored(buildResult)) {
             if (buildResult.error.code === 'BUILD_JAVASCRIPT_ERROR') {

package/lib/commands/dev.js

@@ -9,6 +9,7 @@ import { isErrored } from '../errors.js';
 import { printUploadError } from '../print-errors.js';
 import { addAuxxHiddenDirectoryToTsConfig } from '../util/add-auxx-hidden-directory-to-ts-config.js';
 import { ensureAppEntryPoint } from '../util/ensure-app-entry-point.js';
+import { ensureAppFieldsTypes } from '../util/ensure-app-fields-types.js';
 import { generateAppEnvTypes } from '../util/generate-app-env-types.js';
 import { generateGitignore } from '../util/generate-gitignore.js';
 import { generateSettingsFiles } from '../util/generate-settings-files.js';
@@ -69,6 +70,7 @@ export const dev = new Command('dev')
     else if (appEnvTypesResult.value === 'skipped_unmanaged') {
         process.stderr.write(chalk.yellow('Skipping src/auxx-env.d.ts generation because the existing file is unmanaged. Add imports for @auxx/sdk/client and @auxx/sdk/global manually.\n'));
     }
+    await ensureAppFieldsTypes();
     if (USE_SETTINGS) {
         const updateTsconfigResult = await addAuxxHiddenDirectoryToTsConfig();
         if (isErrored(updateTsconfigResult)) {

package/lib/commands/version/create/bundle-javascript.js

@@ -28,7 +28,13 @@ export async function bundleJavaScript() {
     }
     const settingsSchema = await compileAndExtractSettingsSchema();
     const catalogResult = await compileAndExtractCatalog();
-    const catalog = isErrored(catalogResult) ? undefined : catalogResult.value;
+    if (isErrored(catalogResult)) {
+        return errored({
+            code: 'ERROR_EXTRACTING_CATALOG',
+            error: catalogResult.error,
+        });
+    }
+    const catalog = catalogResult.value;
     return complete({
         bundles: [builds.client.outputFiles[0].text, builds.server.outputFiles[0].text],
         settingsSchema,

package/lib/commands/version/create.js

@@ -16,11 +16,13 @@ import { loadAuxxCliVersion } from '../../util/load-auxx-cli-version.js';
 import { spinnerify } from '../../util/spinner.js';
 import { printJsError } from '../../util/typescript.js';
 import { uploadBundle } from '../../util/upload-bundle.js';
+import { validateTypeScriptOrExit } from '../build/validate-typescript.js';
 import { printBuildContextError } from '../dev/prepare-build-context.js';
 import { bundleJavaScript } from './create/bundle-javascript.js';
 export const versionCreate = new Command('create')
     .description('Create a new deployment of your auxx app')
-    .action(async () => {
+    .option('--publish', 'Submit the deployment for review and publish it once approved')
+    .action(async (options) => {
     if (USE_APP_TS) {
         const appEntryPointResult = await ensureAppEntryPoint();
         if (isErrored(appEntryPointResult)) {
@@ -33,6 +35,7 @@ export const versionCreate = new Command('create')
             exitWithMissingAppSettings();
         }
     }
+    await validateTypeScriptOrExit();
     await authenticator.ensureAuthed();
     const appSlugResult = await getAppSlugFromPackageJson();
     if (isErrored(appSlugResult)) {
@@ -59,6 +62,15 @@ export const versionCreate = new Command('create')
                 printBuildContextError(error);
             }
         }
+        else if (bundleResult.error.code === 'ERROR_EXTRACTING_CATALOG') {
+            const catalogError = bundleResult.error.error;
+            const detail = 'message' in catalogError
+                ? catalogError.message
+                : 'error' in catalogError
+                    ? catalogError.error.message
+                    : '';
+            process.stderr.write(`${chalk.red('✖ ')}Catalog extraction failed (${catalogError.code})${detail ? `: ${detail}` : ''}\n`);
+        }
         else {
             printBuildContextError(bundleResult.error.error);
         }
@@ -117,6 +129,7 @@ export const versionCreate = new Command('create')
             settingsSchema,
             catalog,
             metadata: { cliVersion },
+            publish: options.publish,
         });
         if (isErrored(result)) {
             printFetcherError('Error creating deployment', result);
@@ -129,6 +142,26 @@ export const versionCreate = new Command('create')
         process.exit(1);
     }
     const deployment = deployResult.value;
-    process.stdout.write(`\nDeployment ${chalk.green(deployment.version ?? deployment.deploymentId)} created!\n\n`);
+    if (deployment.unchanged) {
+        process.stdout.write(`\n${chalk.gray('●')} Unchanged — skipped (${deployment.version ?? deployment.deploymentId})\n\n`);
+        process.exit(0);
+    }
+    process.stdout.write(`\nDeployment ${chalk.green(deployment.version ?? deployment.deploymentId)} created!\n`);
+    if (options.publish) {
+        if (deployment.publishError) {
+            process.stderr.write(`${chalk.red('✖ ')}Publish failed: ${deployment.publishError}\n`);
+            process.exit(1);
+        }
+        if (deployment.status === 'published') {
+            process.stdout.write(`${chalk.green('✓ ')}Published — live for installed organizations\n`);
+        }
+        else if (deployment.status === 'pending-review') {
+            process.stdout.write(`${chalk.yellow('● ')}Submitted for review (publishes on approval)\n`);
+        }
+        else if (deployment.status) {
+            process.stdout.write(`Status: ${deployment.status}\n`);
+        }
+    }
+    process.stdout.write('\n');
     process.exit(0);
 });

package/lib/constants/app-fields-files.js

@@ -0,0 +1 @@
+export const APP_FIELDS_TYPES_FILENAME = 'app-fields.d.ts';

package/lib/env.js

@@ -6,3 +6,4 @@ export const AUTH_API = `${APP_URL}/api/auth`;
 export const USE_APP_TS = process.env.USE_APP_TS !== 'false';
 export const USE_SETTINGS = process.env.USE_SETTINGS !== 'false';
 export const SDK_CLIENT_ID = process.env.AUXX_SDK_CLIENT_ID || 'auxx-sdk-cli';
+export const AUXX_API_KEY = process.env.AUXX_API_KEY;

package/lib/root/app.d.ts

@@ -1,4 +1,5 @@
 import type { BulkRecordAction, RecordAction, RecordWidget } from '../client/record-actions.js';
+import type { AppFieldDefinition } from './fields/index.js';
 import type { ScopedSettingsSchema } from './settings/settings-schema.js';
 import type { ToolDefinition, Toolset } from './tools/types.js';
 import type { Trigger, WorkflowBlock } from './workflow/types.js';
@@ -48,6 +49,7 @@ export interface App {
     };
     readonly tools?: ReadonlyArray<ToolDefinition>;
     readonly toolsets?: ReadonlyArray<Toolset>;
+    readonly fields?: ReadonlyArray<AppFieldDefinition>;
     readonly settings?: {
         readonly organization?: ScopedSettingsSchema;
     };

package/lib/root/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/root/app.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC/F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAIjE,MAAM,WAAW,UAAU;IAEzB,QAAQ,EAAE,SAAS,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,CAAA;IAE/D,OAAO,EAAE,CAAC,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC,EAAE,CAAA;IAExC,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAKD,MAAM,WAAW,WAAW;IAE1B,IAAI,EAAE,MAAM,CAAA;IAEZ,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAE1B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAuBD,MAAM,CAAC,OAAO,WAAW,GAAG,CAAC;IAC3B,UAAU,MAAM,CAAC;QACf,KAAK,MAAM,GAAG,YAAY,CAAA;QAC1B,KAAK,UAAU,GAAG,gBAAgB,CAAA;QAClC,KAAK,MAAM,GAAG,YAAY,CAAA;KAC3B;IACD,UAAU,QAAQ,CAAC,GAAE;IACrB,UAAU,QAAQ,CAAC,GAAE;CACtB;AAED,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;KAC5C,CAAA;IAED,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,OAAO,CAAC,EAAE;YACjB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACpC,CAAA;QACD,QAAQ,CAAC,OAAO,CAAC,EAAE;YACjB,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACrC,CAAA;QACD,QAAQ,CAAC,UAAU,CAAC,EAAE;YACpB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACpC,CAAA;KACF,CAAA;IAED,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAElB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,CAAA;QAEjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;KAC9B,CAAA;IAOD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;IAK9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAE1C,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;KAC7C,CAAA;CAIF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/root/app.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC/F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAIjE,MAAM,WAAW,UAAU;IAEzB,QAAQ,EAAE,SAAS,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,CAAA;IAE/D,OAAO,EAAE,CAAC,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC,EAAE,CAAA;IAExC,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAKD,MAAM,WAAW,WAAW;IAE1B,IAAI,EAAE,MAAM,CAAA;IAEZ,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAE1B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAuBD,MAAM,CAAC,OAAO,WAAW,GAAG,CAAC;IAC3B,UAAU,MAAM,CAAC;QACf,KAAK,MAAM,GAAG,YAAY,CAAA;QAC1B,KAAK,UAAU,GAAG,gBAAgB,CAAA;QAClC,KAAK,MAAM,GAAG,YAAY,CAAA;KAC3B;IACD,UAAU,QAAQ,CAAC,GAAE;IACrB,UAAU,QAAQ,CAAC,GAAE;CACtB;AAED,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;KAC5C,CAAA;IAED,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,OAAO,CAAC,EAAE;YACjB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACpC,CAAA;QACD,QAAQ,CAAC,OAAO,CAAC,EAAE;YACjB,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACrC,CAAA;QACD,QAAQ,CAAC,UAAU,CAAC,EAAE;YACpB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACpC,CAAA;KACF,CAAA;IAED,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAElB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,CAAA;QAEjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;KAC9B,CAAA;IAOD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;IAK9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAQ1C,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;IAEnD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;KAC7C,CAAA;CAIF"}

package/lib/root/fields/define-field.d.ts

@@ -0,0 +1,67 @@
+import type { EntityRefKind } from '../tools/types.js';
+import type { FieldCapabilities, FieldScope, FieldSelectOption, FieldType } from './field-types.js';
+type SelectFieldType = 'SINGLE_SELECT' | 'MULTI_SELECT' | 'TAGS';
+type ScalarFieldType = Exclude<FieldType, SelectFieldType | 'RELATIONSHIP' | 'CALC' | 'ACTOR'>;
+interface BaseAppFieldDefinition {
+    readonly appFieldKey: string;
+    readonly targetEntity: EntityRefKind;
+    readonly scope: FieldScope;
+    readonly name: string;
+    readonly description?: string;
+    readonly capabilities?: FieldCapabilities;
+}
+interface ScalarAppFieldDefinition extends BaseAppFieldDefinition {
+    readonly type: ScalarFieldType;
+    readonly options?: never;
+    readonly relationship?: never;
+    readonly calc?: never;
+}
+interface SelectAppFieldDefinition extends BaseAppFieldDefinition {
+    readonly type: SelectFieldType;
+    readonly options: readonly FieldSelectOption[];
+    readonly relationship?: never;
+    readonly calc?: never;
+}
+interface RelationshipAppFieldDefinition extends BaseAppFieldDefinition {
+    readonly type: 'RELATIONSHIP';
+    readonly relationship: {
+        readonly targetEntity: EntityRefKind;
+        readonly cardinality: 'one' | 'many';
+    };
+    readonly options?: never;
+    readonly calc?: never;
+}
+interface CalcAppFieldDefinition extends BaseAppFieldDefinition {
+    readonly type: 'CALC';
+    readonly calc: {
+        readonly expression: string;
+    };
+    readonly options?: never;
+    readonly relationship?: never;
+}
+export type AppFieldDefinition = ScalarAppFieldDefinition | SelectAppFieldDefinition | RelationshipAppFieldDefinition | CalcAppFieldDefinition;
+export declare function defineField<const F extends AppFieldDefinition>(field: F): F;
+export declare function defineFields<const F extends readonly AppFieldDefinition[]>(fields: F): F;
+type OptionValues<F> = F extends {
+    options: readonly (infer O)[];
+} ? O extends {
+    value: infer V;
+} ? V : string : string;
+export type FieldValueType<F extends AppFieldDefinition> = F extends {
+    type: 'SINGLE_SELECT';
+} ? OptionValues<F> : F extends {
+    type: 'MULTI_SELECT' | 'TAGS';
+} ? OptionValues<F>[] : F extends {
+    type: 'NUMBER' | 'CURRENCY';
+} ? number : F extends {
+    type: 'CHECKBOX';
+} ? boolean : F extends {
+    type: 'JSON';
+} ? unknown : F extends {
+    type: 'RELATIONSHIP';
+} ? string : string;
+export type AppFieldValues<F extends readonly AppFieldDefinition[]> = {
+    [K in F[number] as K['appFieldKey']]: FieldValueType<K>;
+};
+export {};
+//# sourceMappingURL=define-field.d.ts.map

package/lib/root/fields/define-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-field.d.ts","sourceRoot":"","sources":["../../../src/root/fields/define-field.ts"],"names":[],"mappings":"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"}

package/lib/root/fields/define-field.js

@@ -0,0 +1,21 @@
+const APP_FIELD_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+export function defineField(field) {
+    if (!APP_FIELD_KEY_RE.test(field.appFieldKey)) {
+        throw new Error(`defineField: invalid appFieldKey "${field.appFieldKey}" — must match ${APP_FIELD_KEY_RE.source}`);
+    }
+    return field;
+}
+export function defineFields(fields) {
+    const seen = new Set();
+    for (const field of fields) {
+        if (!APP_FIELD_KEY_RE.test(field.appFieldKey)) {
+            throw new Error(`defineFields: invalid appFieldKey "${field.appFieldKey}" — must match ${APP_FIELD_KEY_RE.source}`);
+        }
+        const dedupeKey = `${field.targetEntity}:${field.appFieldKey}`;
+        if (seen.has(dedupeKey)) {
+            throw new Error(`defineFields: duplicate appFieldKey "${field.appFieldKey}" on entity "${field.targetEntity}"`);
+        }
+        seen.add(dedupeKey);
+    }
+    return fields;
+}

package/lib/root/fields/field-types.d.ts

@@ -0,0 +1,47 @@
+export declare const FIELD_TYPES: readonly ["TEXT", "EMAIL", "URL", "RICH_TEXT", "PHONE", "PHONE_INTL", "ADDRESS", "ADDRESS_STRUCT", "FILE", "DATE", "DATETIME", "TIME", "NUMBER", "CURRENCY", "CHECKBOX", "JSON", "NAME", "SINGLE_SELECT", "MULTI_SELECT", "TAGS", "RELATIONSHIP", "CALC", "ACTOR"];
+export type FieldType = (typeof FIELD_TYPES)[number];
+export interface FieldCapabilities {
+    filterable?: boolean;
+    sortable?: boolean;
+    creatable?: boolean;
+    updatable?: boolean;
+    required?: boolean;
+    unique?: boolean;
+    computed?: boolean;
+    hidden?: boolean;
+}
+export type FieldScope = 'installation' | 'connection';
+export interface FieldSelectOption {
+    value: string;
+    label?: string;
+    color?: string;
+}
+export interface FieldTypeValueMap {
+    TEXT: string;
+    EMAIL: string;
+    URL: string;
+    RICH_TEXT: string;
+    PHONE: string;
+    PHONE_INTL: string;
+    ADDRESS: string;
+    DATE: string;
+    DATETIME: string;
+    TIME: string;
+    NUMBER: number;
+    CURRENCY: number;
+    CHECKBOX: boolean;
+    JSON: unknown;
+    NAME: string;
+    SINGLE_SELECT: string;
+    MULTI_SELECT: string[];
+    TAGS: string[];
+    ADDRESS_STRUCT: Record<string, unknown>;
+    FILE: {
+        url: string;
+        name?: string;
+    };
+    RELATIONSHIP: string;
+    CALC: string | number;
+    ACTOR: string | string[];
+}
+//# sourceMappingURL=field-types.d.ts.map

package/lib/root/fields/field-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-types.d.ts","sourceRoot":"","sources":["../../../src/root/fields/field-types.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,WAAW,oQAwBd,CAAA;AAGV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAOpD,MAAM,WAAW,iBAAiB;IAEhC,UAAU,CAAC,EAAE,OAAO,CAAA;IAEpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB,SAAS,CAAC,EAAE,OAAO,CAAA;IAGnB,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAIlB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAGD,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,YAAY,CAAA;AAGtD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAQD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CACzB"}

package/lib/root/fields/field-types.js

@@ -0,0 +1,25 @@
+export const FIELD_TYPES = [
+    'TEXT',
+    'EMAIL',
+    'URL',
+    'RICH_TEXT',
+    'PHONE',
+    'PHONE_INTL',
+    'ADDRESS',
+    'ADDRESS_STRUCT',
+    'FILE',
+    'DATE',
+    'DATETIME',
+    'TIME',
+    'NUMBER',
+    'CURRENCY',
+    'CHECKBOX',
+    'JSON',
+    'NAME',
+    'SINGLE_SELECT',
+    'MULTI_SELECT',
+    'TAGS',
+    'RELATIONSHIP',
+    'CALC',
+    'ACTOR',
+];

package/lib/root/fields/index.d.ts

@@ -0,0 +1,3 @@
+export { type AppFieldDefinition, type AppFieldValues, defineField, defineFields, type FieldValueType, } from './define-field.js';
+export { FIELD_TYPES, type FieldCapabilities, type FieldScope, type FieldSelectOption, type FieldType, type FieldTypeValueMap, } from './field-types.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/root/fields/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/root/fields/index.ts"],"names":[],"mappings":"AA0BA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,WAAW,EACX,YAAY,EACZ,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAA"}

package/lib/root/fields/index.js

@@ -0,0 +1,2 @@
+export { defineField, defineFields, } from './define-field.js';
+export { FIELD_TYPES, } from './field-types.js';

package/lib/root/index.d.ts

@@ -1,6 +1,7 @@
 export type { BulkRecordAction, RecordAction, RecordActionContext, } from '../client/record-actions.js';
 export type { TriggerContext, WorkflowContext, WorkflowInput, WorkflowOutput, } from '../server/workflow/index.js';
 export type { App, AppSettings, Permission } from './app.js';
+export { type AppFieldDefinition, type AppFieldValues, defineField, defineFields, FIELD_TYPES, type FieldCapabilities, type FieldScope, type FieldSelectOption, type FieldType, type FieldTypeValueMap, type FieldValueType, } from './fields/index.js';
 export { Settings } from './settings/index.js';
 export type { BaseSettingOptions, BooleanSettingOptions, NumberSettingOptions, SelectSettingOptions, SettingsBooleanNode, SettingsNode, SettingsNumberNode, SettingsSchema, SettingsSelectNode, SettingsStringNode, SettingsStructNode, StringSettingOptions, StructSettingOptions, } from './settings/settings-schema.js';
 export type { AuxxRefMeta, EntityRefKind, ToolActionContext, ToolActionEntity, ToolActionParticipant, ToolActionSurface, ToolAgentSurface, ToolConfig, ToolDefinition, ToolExecuteContext, Toolset, } from './tools/index.js';

package/lib/root/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/root/index.ts"],"names":[],"mappings":"AASA,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,GACf,MAAM,6BAA6B,CAAA;AACpC,YAAY,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAE9C,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,OAAO,GACR,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAA;AACtD,YAAY,EACV,iBAAiB,EACjB,QAAQ,EACR,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EAEZ,kBAAkB,EAClB,kBAAkB,EAClB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EAEjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,GACb,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/root/index.ts"],"names":[],"mappings":"AASA,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,GACf,MAAM,6BAA6B,CAAA;AACpC,YAAY,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE5D,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAE9C,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,OAAO,GACR,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAA;AACtD,YAAY,EACV,iBAAiB,EACjB,QAAQ,EACR,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EAEZ,kBAAkB,EAClB,kBAAkB,EAClB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EAEjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,GACb,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA"}

package/lib/root/index.js

@@ -1,3 +1,4 @@
+export { defineField, defineFields, FIELD_TYPES, } from './fields/index.js';
 export { Settings } from './settings/index.js';
 export { defineTool, refs, z } from './tools/index.js';
 export { defineTrigger, Workflow } from './workflow/index.js';

package/lib/root/tools/define-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../../../src/root/tools/define-tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAkBhD,wBAAgB,UAAU,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EAAE,OAAO,SAAS,CAAC,CAAC,UAAU,EAClF,IAAI,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAKjC"}
+{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../../../src/root/tools/define-tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAkBhD,wBAAgB,UAAU,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EAAE,OAAO,SAAS,CAAC,CAAC,UAAU,EAClF,IAAI,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BjC"}

package/lib/root/tools/define-tool.js

@@ -3,5 +3,19 @@ export function defineTool(tool) {
     if (!TOOL_ID_RE.test(tool.id)) {
         throw new Error(`defineTool: invalid id "${tool.id}" — must match ${TOOL_ID_RE.source}`);
     }
+    if (tool.exampleOutput !== undefined) {
+        const parsed = tool.outputs.safeParse(tool.exampleOutput);
+        if (!parsed.success) {
+            throw new Error(`defineTool: tool "${tool.id}" exampleOutput does not satisfy its outputs schema — ${parsed.error.message}`);
+        }
+        try {
+            if (JSON.stringify(tool.exampleOutput) === undefined) {
+                throw new Error('serializes to undefined (function or top-level undefined)');
+            }
+        }
+        catch (err) {
+            throw new Error(`defineTool: tool "${tool.id}" exampleOutput is not JSON-serializable — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     return tool;
 }

package/lib/root/tools/types.d.ts

@@ -26,12 +26,27 @@ export interface ToolConfig {
     readonly idempotent?: boolean;
     readonly streaming?: boolean;
 }
+export type AgentSurface = 'internal' | 'chat' | 'email' | 'builder';
 export interface ToolAgentSurface {
     readonly name?: string;
     readonly description?: string;
     readonly toolsetSlug?: string;
     readonly streaming?: boolean;
     readonly idempotent?: boolean;
+    readonly surfaces?: AgentSurface[];
+    readonly externalSafe?: boolean;
+    readonly inputBindings?: ReadonlyArray<{
+        name: string;
+        default: {
+            kind: 'var';
+            ref: string | readonly string[];
+        } | {
+            kind: 'const';
+            value: unknown;
+        } | {
+            kind: 'model';
+        };
+    }>;
 }
 export interface ToolActionSurface {
     readonly label: string;
@@ -51,6 +66,7 @@ export interface ToolDefinition<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOut
     readonly icon?: string | ComponentType;
     readonly inputs: TInput;
     readonly outputs: TOutput;
+    readonly exampleOutput?: z.output<TOutput>;
     readonly config?: ToolConfig;
     readonly execute: (input: z.input<TInput>, ctx: ToolExecuteContext) => Promise<z.output<TOutput>> | AsyncGenerator<unknown, z.output<TOutput>>;
     readonly agent?: ToolAgentSurface;
@@ -71,27 +87,5 @@ export interface ToolExecuteContext {
     readonly sessionId: string;
     readonly agentId: string | null;
     readonly triggerId: string | null;
-    readonly entities: {
-        findByIntegrationId: (input: {
-            kind: EntityRefKind;
-            source: string;
-            externalId: string;
-        }) => Promise<{
-            recordId: string;
-            displayName: string | null;
-        } | null>;
-        findContactByEmail: (input: {
-            email: string;
-        }) => Promise<{
-            recordId: string;
-            displayName: string | null;
-        } | null>;
-        findContactByPhone: (input: {
-            phone: string;
-        }) => Promise<{
-            recordId: string;
-            displayName: string | null;
-        } | null>;
-    };
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/root/tools/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/root/tools/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/root/tools/types.ts"],"names":[],"mappings":"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"}

package/lib/root/workflow/types.d.ts

@@ -121,6 +121,7 @@ export interface PollingState {
     state: Record<string, unknown>;
     connection: {
         value: string;
+        fields?: Record<string, string>;
         metadata?: Record<string, unknown>;
     } | null;
 }