@auxx/sdk 0.0.25 → 0.0.27

package/lib/build/server/generate-server-entry.js

@@ -172,7 +172,7 @@ export async function generateServerEntry({ appDirAbsolute, srcDirAbsolute, webh
         // Build __AUXX_DATA_CONNECTORS__ — the connector registry read by the
         // lambda data-connector-executor. Mirrors __AUXX_TOOLS__: the executor
         // reads execute({ streamKey, mode, state, connection, config }) off this
-        // global. See plans/data-connectors/claude/03-connectors-and-sources.md §4.
+        // global. See docs/app-fields-and-entities-guide.md.
         const __AUXX_DATA_CONNECTORS__ = {};
 
         for (const [connectorId, handlers] of dataConnectorModulesMap.entries()) {

package/lib/root/app.d.ts

@@ -1,5 +1,6 @@
 import type { BulkRecordAction, RecordAction, RecordWidget } from '../client/record-actions.js';
 import type { DataConnectorDefinition } from './data-connectors/types.js';
+import type { EntityDecl } from './entities/index.js';
 import type { AppFieldDefinition } from './fields/index.js';
 import type { ScopedSettingsSchema } from './settings/settings-schema.js';
 import type { ToolDefinition, Toolset } from './tools/types.js';
@@ -51,6 +52,7 @@ export interface App {
     readonly tools?: ReadonlyArray<ToolDefinition>;
     readonly toolsets?: ReadonlyArray<Toolset>;
     readonly fields?: ReadonlyArray<AppFieldDefinition>;
+    readonly entities?: ReadonlyArray<EntityDecl>;
     readonly dataConnectors?: ReadonlyArray<DataConnectorDefinition>;
     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":"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"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/root/app.ts"],"names":[],"mappings":"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"}

package/lib/root/data-connectors/define-data-connector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-data-connector.d.ts","sourceRoot":"","sources":["../../../src/root/data-connectors/define-data-connector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAyDzD,wBAAgB,mBAAmB,CAAC,aAAa,SAAS,CAAC,CAAC,UAAU,EACpE,SAAS,EAAE,uBAAuB,CAAC,aAAa,CAAC,GAChD,uBAAuB,CAAC,aAAa,CAAC,CA6CxC"}
+{"version":3,"file":"define-data-connector.d.ts","sourceRoot":"","sources":["../../../src/root/data-connectors/define-data-connector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,EAAoB,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAqL3E,wBAAgB,mBAAmB,CAAC,aAAa,SAAS,CAAC,CAAC,UAAU,EACpE,SAAS,EAAE,uBAAuB,CAAC,aAAa,CAAC,GAChD,uBAAuB,CAAC,aAAa,CAAC,CA2CxC"}

package/lib/root/data-connectors/define-data-connector.js

@@ -1,4 +1,57 @@
 const CONNECTOR_ID_RE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/;
+function assertValidMapping(connectorId, streamKey, mapping) {
+    const target = mapping.target;
+    const hasEntityKey = 'entityKey' in target;
+    const hasEntityKind = 'entityKind' in target;
+    if (hasEntityKey === hasEntityKind) {
+        throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": target must name exactly one of entityKey or entityKind`);
+    }
+    if (hasEntityKey) {
+        if (mapping.connectionFields) {
+            throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": connectionFields is only valid on a contributing (entityKind) mapping`);
+        }
+        for (const field of mapping.fields ?? []) {
+            const owned = field;
+            if (!owned.key || !owned.sourcePath) {
+                throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": every owned field needs a key and a sourcePath`);
+            }
+        }
+        return;
+    }
+    const contributing = mapping;
+    for (const field of contributing.fields ?? []) {
+        if (field.constant !== undefined) {
+            if (field.sourcePath) {
+                throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": field with constant ${JSON.stringify(field.constant)} cannot also set a sourcePath`);
+            }
+            if (!field.target || field.appField) {
+                throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": a constant field needs a target and cannot set appField`);
+            }
+            if (field.match) {
+                throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": constant field "${String(field.target)}" cannot be a match key`);
+            }
+            const t = typeof field.constant;
+            if (t !== 'string' && t !== 'number' && t !== 'boolean') {
+                throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": constant field "${String(field.target)}" must be a string, number, or boolean`);
+            }
+            continue;
+        }
+        if (!field.sourcePath) {
+            throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": every contributing field needs a sourcePath or a constant`);
+        }
+        if (field.target && field.appField) {
+            throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": field "${field.sourcePath}" cannot set both target and appField`);
+        }
+        if (!field.target && !field.appField && !(field.type && field.name)) {
+            throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": field "${field.sourcePath}" needs a target, an appField, or both type and name (source-only projection)`);
+        }
+    }
+    for (const conn of contributing.connectionFields ?? []) {
+        if (!conn.appField || !conn.from) {
+            throw new Error(`defineDataConnector: connector "${connectorId}" stream "${streamKey}" mapping "${mapping.rootPath}": every connectionFields entry needs appField and from`);
+        }
+    }
+}
 export function defineDataConnector(connector) {
     if (!CONNECTOR_ID_RE.test(connector.id)) {
         throw new Error(`defineDataConnector: invalid id "${connector.id}" — must match ${CONNECTOR_ID_RE.source}`);
@@ -15,8 +68,8 @@ export function defineDataConnector(connector) {
             throw new Error(`defineDataConnector: connector "${connector.id}" has duplicate stream key "${stream.key}"`);
         }
         seenStreamKeys.add(stream.key);
-        if (!stream.fields[stream.displayFieldKey]) {
-            throw new Error(`defineDataConnector: stream "${stream.key}" displayFieldKey "${stream.displayFieldKey}" is not a declared field`);
+        for (const mapping of stream.mappings ?? []) {
+            assertValidMapping(connector.id, stream.key, mapping);
         }
         if (stream.exampleRecord !== undefined) {
             try {

package/lib/root/data-connectors/index.d.ts

@@ -1,3 +1,3 @@
 export { defineDataConnector } from './define-data-connector.js';
-export type { ConnectorConnection, ConnectorDefaultMapping, ConnectorEntityDecl, ConnectorExecute, ConnectorExecuteArgs, ConnectorFetchResult, ConnectorFieldCapabilities, ConnectorFieldDecl, ConnectorRecord, ConnectorRelationshipDecl, ConnectorRelationshipTargetRef, ConnectorStreamDecl, ConnectorStreamState, DataConnectorDefinition, } from './types.js';
+export type { ConnectorConnection, ConnectorConnectionField, ConnectorContributingFieldConstant, ConnectorContributingFieldSourceOnly, ConnectorContributingFieldToAppField, ConnectorContributingFieldToTarget, ConnectorContributingMappingField, ConnectorExecute, ConnectorExecuteArgs, ConnectorFetchResult, ConnectorMapping, ConnectorOwnedMappingField, ConnectorRecord, ConnectorStreamDecl, ConnectorStreamState, ContributingConnectorMapping, DataConnectorDefinition, FieldMergeStrategy, OwnedConnectorMapping, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/root/data-connectors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/root/data-connectors/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,eAAe,EACf,yBAAyB,EACzB,8BAA8B,EAC9B,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/root/data-connectors/index.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,kCAAkC,EAClC,oCAAoC,EACpC,oCAAoC,EACpC,kCAAkC,EAClC,iCAAiC,EACjC,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,0BAA0B,EAC1B,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,YAAY,CAAA"}

package/lib/root/data-connectors/types.d.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod/v4';
-import type { FieldSelectOption, FieldType } from '../fields/field-types.js';
-import type { ActionInputHint } from '../tools/types.js';
+import type { FieldType } from '../fields/field-types.js';
+import type { ActionInputHint, EntityRefKind } from '../tools/types.js';
 export interface ConnectorRecord {
     streamKey: string;
     externalId: string;
@@ -22,70 +22,76 @@ export interface ConnectorFetchResult {
         retryAfterMs?: number;
     };
 }
-export interface ConnectorFieldCapabilities {
-    hidden?: boolean;
-    filterable?: boolean;
-}
-export interface ConnectorFieldDecl {
-    sourcePath: string;
-    type: FieldType;
-    name: string;
-    pii?: boolean;
-    capabilities?: ConnectorFieldCapabilities;
-    options?: FieldSelectOption[];
-    addressComponents?: string[];
-    isExternalId?: boolean;
-}
-export interface ConnectorEntityDecl {
-    key: string;
-    apiSlug: string;
-    singular: string;
-    plural: string;
-    primaryDisplayField?: string;
-    avatarField?: string;
-}
-export type ConnectorRelationshipTargetRef = {
-    ownedKey: string;
-} | {
-    entityKind: string;
-};
-export interface ConnectorRelationshipDecl {
-    fieldKey: string;
-    name: string;
-    cardinality: 'has_many' | 'has_one' | 'belongs_to' | 'many_to_many';
-    inverseName: string;
-    targetRef?: ConnectorRelationshipTargetRef;
-}
-export interface ConnectorDefaultMapping {
-    rootPath: string;
-    parentRootPath?: string;
-    linkMode?: 'upsert' | 'reference';
-    relationshipFieldKey?: string;
-    relationship?: ConnectorRelationshipDecl;
-    target: {
-        mode: 'owned';
-        entity: ConnectorEntityDecl;
-    } | {
-        mode: 'contributing';
-        entityKind: string;
-        matchFieldKeys?: string[];
-        fieldBindings?: {
-            sourceFieldKey: string;
-            targetKey?: string;
-            targetAppField?: string;
-        }[];
-        connectionAppFields?: {
-            appFieldKey: string;
-            from: string;
-        }[];
+export type FieldMergeStrategy = 'overwrite' | 'fill_blank' | 'connector_owned_only' | 'manual_review' | 'ignore';
+export interface ConnectorOwnedMappingField {
+    readonly key: string;
+    readonly sourcePath: string;
+}
+interface ConnectorContributingFieldCommon {
+    readonly mergeStrategy?: FieldMergeStrategy;
+}
+interface ConnectorContributingFieldBase extends ConnectorContributingFieldCommon {
+    readonly sourcePath: string;
+    readonly constant?: never;
+    readonly match?: boolean | 'exclusive';
+}
+export interface ConnectorContributingFieldToTarget extends ConnectorContributingFieldBase {
+    readonly target: string;
+    readonly appField?: never;
+    readonly type?: never;
+    readonly name?: never;
+}
+export interface ConnectorContributingFieldToAppField extends ConnectorContributingFieldBase {
+    readonly appField: string;
+    readonly target?: never;
+    readonly type?: never;
+    readonly name?: never;
+}
+export interface ConnectorContributingFieldSourceOnly extends ConnectorContributingFieldBase {
+    readonly type: FieldType;
+    readonly name: string;
+    readonly target?: never;
+    readonly appField?: never;
+}
+export interface ConnectorContributingFieldConstant extends ConnectorContributingFieldCommon {
+    readonly constant: string | number | boolean;
+    readonly target: string;
+    readonly sourcePath?: never;
+    readonly appField?: never;
+    readonly match?: never;
+    readonly type?: never;
+    readonly name?: never;
+}
+export type ConnectorContributingMappingField = ConnectorContributingFieldToTarget | ConnectorContributingFieldToAppField | ConnectorContributingFieldSourceOnly | ConnectorContributingFieldConstant;
+export interface ConnectorConnectionField {
+    readonly appField: string;
+    readonly from: string;
+}
+interface ConnectorMappingBase {
+    readonly rootPath: string;
+    readonly parentRootPath?: string;
+    readonly linkMode?: 'upsert' | 'reference';
+    readonly relationshipFieldKey?: string;
+}
+export interface OwnedConnectorMapping extends ConnectorMappingBase {
+    readonly target: {
+        readonly entityKey: string;
+    };
+    readonly fields?: readonly ConnectorOwnedMappingField[];
+    readonly connectionFields?: never;
+}
+export interface ContributingConnectorMapping extends ConnectorMappingBase {
+    readonly target: {
+        readonly entityKind: EntityRefKind;
     };
+    readonly fields?: readonly ConnectorContributingMappingField[];
+    readonly connectionFields?: readonly ConnectorConnectionField[];
 }
+export type ConnectorMapping = OwnedConnectorMapping | ContributingConnectorMapping;
 export interface ConnectorStreamDecl {
     key: string;
-    displayFieldKey: string;
     syncMode?: 'snapshot' | 'incremental';
-    fields: Record<string, ConnectorFieldDecl>;
-    defaultMappings?: ConnectorDefaultMapping[];
+    mappings: ConnectorMapping[];
     exampleRecord?: Record<string, unknown>;
     webhookTrigger?: {
         filter?: Record<string, unknown>;
@@ -121,4 +127,5 @@ export interface DataConnectorDefinition<TConfigSchema extends z.ZodTypeAny = z.
     };
     execute: ConnectorExecute<z.output<TConfigSchema>>;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

package/lib/root/data-connectors/types.d.ts.map

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

package/lib/root/entities/define-entity.d.ts

@@ -0,0 +1,16 @@
+import { type FieldDecl } from '../fields/define-field.js';
+export interface EntityDecl {
+    readonly key: string;
+    readonly apiSlug: string;
+    readonly singular: string;
+    readonly plural: string;
+    readonly description?: string;
+    readonly icon?: string;
+    readonly color?: string;
+    readonly primaryDisplayField: string;
+    readonly secondaryDisplayField?: string;
+    readonly avatarField?: string;
+    readonly fields: readonly FieldDecl[];
+}
+export declare function defineEntity<const E extends EntityDecl>(entity: E): E;
+//# sourceMappingURL=define-entity.d.ts.map

package/lib/root/entities/define-entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-entity.d.ts","sourceRoot":"","sources":["../../../src/root/entities/define-entity.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAiBpF,MAAM,WAAW,UAAU;IAQzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAGpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IAGvB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IAGpC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAGvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAO7B,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;CACtC;AA+BD,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAgDrE"}

package/lib/root/entities/define-entity.js

@@ -0,0 +1,39 @@
+import { assertValidIdentityField } from '../fields/define-field.js';
+const ENTITY_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+const API_SLUG_RE = /^[a-z][a-z0-9_]*$/;
+export function defineEntity(entity) {
+    if (!ENTITY_KEY_RE.test(entity.key)) {
+        throw new Error(`defineEntity: invalid key "${entity.key}" — must match ${ENTITY_KEY_RE.source}`);
+    }
+    if (!API_SLUG_RE.test(entity.apiSlug)) {
+        throw new Error(`defineEntity "${entity.key}": invalid apiSlug "${entity.apiSlug}" — must match ${API_SLUG_RE.source}`);
+    }
+    const fieldKeys = new Set();
+    let identityFieldKey;
+    for (const field of entity.fields) {
+        if (!ENTITY_KEY_RE.test(field.key)) {
+            throw new Error(`defineEntity "${entity.key}": invalid field key "${field.key}" — must match ${ENTITY_KEY_RE.source}`);
+        }
+        if (fieldKeys.has(field.key)) {
+            throw new Error(`defineEntity "${entity.key}": duplicate field key "${field.key}"`);
+        }
+        fieldKeys.add(field.key);
+        assertValidIdentityField(field);
+        if (field.identity) {
+            if (identityFieldKey !== undefined) {
+                throw new Error(`defineEntity "${entity.key}": more than one identity field ("${identityFieldKey}" and "${field.key}") — at most one identity field is allowed per entity`);
+            }
+            identityFieldKey = field.key;
+        }
+    }
+    for (const [label, fieldKey] of [
+        ['primaryDisplayField', entity.primaryDisplayField],
+        ['secondaryDisplayField', entity.secondaryDisplayField],
+        ['avatarField', entity.avatarField],
+    ]) {
+        if (fieldKey !== undefined && !fieldKeys.has(fieldKey)) {
+            throw new Error(`defineEntity "${entity.key}": ${label} "${fieldKey}" is not a declared field`);
+        }
+    }
+    return entity;
+}

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

@@ -0,0 +1,2 @@
+export { defineEntity, type EntityDecl } from './define-entity.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/root/entities/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAA"}

package/lib/root/entities/index.js

@@ -0,0 +1 @@
+export { defineEntity } from './define-entity.js';

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

@@ -1,46 +1,66 @@
 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;
+type ScalarFieldType = Exclude<FieldType, SelectFieldType | 'RELATIONSHIP' | 'CALC' | 'ADDRESS_STRUCT' | 'ACTOR'>;
+export type FieldDecl = ScalarFieldDecl | AddressStructFieldDecl | SelectFieldDecl | RelationshipFieldDecl | CalcFieldDecl;
+interface BaseFieldDecl {
+    readonly key: string;
     readonly name: string;
     readonly description?: string;
     readonly capabilities?: FieldCapabilities;
     readonly identity?: boolean;
+    readonly pii?: boolean;
 }
-interface ScalarAppFieldDefinition extends BaseAppFieldDefinition {
+interface ScalarFieldDecl extends BaseFieldDecl {
     readonly type: ScalarFieldType;
     readonly options?: never;
+    readonly addressComponents?: never;
     readonly relationship?: never;
     readonly calc?: never;
 }
-interface SelectAppFieldDefinition extends BaseAppFieldDefinition {
+interface AddressStructFieldDecl extends BaseFieldDecl {
+    readonly type: 'ADDRESS_STRUCT';
+    readonly addressComponents?: readonly string[];
+    readonly options?: never;
+    readonly relationship?: never;
+    readonly calc?: never;
+}
+interface SelectFieldDecl extends BaseFieldDecl {
     readonly type: SelectFieldType;
     readonly options: readonly FieldSelectOption[];
+    readonly addressComponents?: never;
     readonly relationship?: never;
     readonly calc?: never;
 }
-interface RelationshipAppFieldDefinition extends BaseAppFieldDefinition {
+interface RelationshipFieldDecl extends BaseFieldDecl {
     readonly type: 'RELATIONSHIP';
     readonly relationship: {
-        readonly targetEntity: EntityRefKind;
-        readonly cardinality: 'one' | 'many';
+        readonly target: {
+            readonly entityKey: string;
+        } | {
+            readonly entityKind: EntityRefKind;
+        };
+        readonly cardinality: 'has_many' | 'has_one' | 'belongs_to' | 'many_to_many';
+        readonly inverseName?: string;
     };
     readonly options?: never;
+    readonly addressComponents?: never;
     readonly calc?: never;
 }
-interface CalcAppFieldDefinition extends BaseAppFieldDefinition {
+interface CalcFieldDecl extends BaseFieldDecl {
     readonly type: 'CALC';
     readonly calc: {
         readonly expression: string;
     };
     readonly options?: never;
+    readonly addressComponents?: never;
     readonly relationship?: never;
 }
-export type AppFieldDefinition = ScalarAppFieldDefinition | SelectAppFieldDefinition | RelationshipAppFieldDefinition | CalcAppFieldDefinition;
+export type AppFieldDefinition = FieldDecl & {
+    readonly targetEntity: EntityRefKind;
+    readonly scope: FieldScope;
+};
+export declare function assertValidIdentityField(field: FieldDecl): void;
 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 {
@@ -48,7 +68,7 @@ type OptionValues<F> = F extends {
 } ? O extends {
     value: infer V;
 } ? V : string : string;
-export type FieldValueType<F extends AppFieldDefinition> = F extends {
+export type FieldValueType<F extends FieldDecl> = F extends {
     type: 'SINGLE_SELECT';
 } ? OptionValues<F> : F extends {
     type: 'MULTI_SELECT' | 'TAGS';
@@ -61,8 +81,8 @@ export type FieldValueType<F extends AppFieldDefinition> = F extends {
 } ? unknown : F extends {
     type: 'RELATIONSHIP';
 } ? string : string;
-export type AppFieldValues<F extends readonly AppFieldDefinition[]> = {
-    [K in F[number] as K['appFieldKey']]: FieldValueType<K>;
+export type AppFieldValues<F extends readonly FieldDecl[]> = {
+    [K in F[number] as K['key']]: FieldValueType<K>;
 };
 export {};
 //# sourceMappingURL=define-field.d.ts.map

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

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

@@ -1,4 +1,4 @@
-const APP_FIELD_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+const FIELD_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
 const NON_IDENTITY_FIELD_TYPES = new Set([
     'RELATIONSHIP',
     'CALC',
@@ -7,19 +7,20 @@ const NON_IDENTITY_FIELD_TYPES = new Set([
     'TAGS',
     'FILE',
     'JSON',
+    'ADDRESS_STRUCT',
     'ACTOR',
 ]);
-function assertValidIdentityField(field) {
+export function assertValidIdentityField(field) {
     if (!field.identity)
         return;
     if (NON_IDENTITY_FIELD_TYPES.has(field.type)) {
-        throw new Error(`defineField: "${field.appFieldKey}" cannot be identity: true with type "${field.type}" — ` +
+        throw new Error(`defineField: "${field.key}" cannot be identity: true with type "${field.type}" — ` +
             'identity fields must be a scalar single-value type (TEXT unless another scalar is needed)');
     }
 }
 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}`);
+    if (!FIELD_KEY_RE.test(field.key)) {
+        throw new Error(`defineField: invalid key "${field.key}" — must match ${FIELD_KEY_RE.source}`);
     }
     assertValidIdentityField(field);
     return field;
@@ -27,12 +28,12 @@ export function defineField(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}`);
+        if (!FIELD_KEY_RE.test(field.key)) {
+            throw new Error(`defineFields: invalid key "${field.key}" — must match ${FIELD_KEY_RE.source}`);
         }
-        const dedupeKey = `${field.targetEntity}:${field.appFieldKey}`;
+        const dedupeKey = `${field.targetEntity}:${field.key}`;
         if (seen.has(dedupeKey)) {
-            throw new Error(`defineFields: duplicate appFieldKey "${field.appFieldKey}" on entity "${field.targetEntity}"`);
+            throw new Error(`defineFields: duplicate key "${field.key}" on entity "${field.targetEntity}"`);
         }
         seen.add(dedupeKey);
         assertValidIdentityField(field);

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

@@ -1,4 +1,4 @@
-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 declare const FIELD_TYPES: readonly ["TEXT", "EMAIL", "URL", "RICH_TEXT", "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;
@@ -21,7 +21,6 @@ export interface FieldTypeValueMap {
     EMAIL: string;
     URL: string;
     RICH_TEXT: string;
-    PHONE: string;
     PHONE_INTL: string;
     ADDRESS: string;
     DATE: string;

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

@@ -1 +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"}
+{"version":3,"file":"field-types.d.ts","sourceRoot":"","sources":["../../../src/root/fields/field-types.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,WAAW,2PAuBd,CAAA;AAQV,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;AASD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,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

@@ -3,7 +3,6 @@ export const FIELD_TYPES = [
     'EMAIL',
     'URL',
     'RICH_TEXT',
-    'PHONE',
     'PHONE_INTL',
     'ADDRESS',
     'ADDRESS_STRUCT',

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

@@ -1,3 +1,3 @@
-export { type AppFieldDefinition, type AppFieldValues, defineField, defineFields, type FieldValueType, } from './define-field.js';
+export { type AppFieldDefinition, type AppFieldValues, defineField, defineFields, type FieldDecl, 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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/root/fields/index.ts"],"names":[],"mappings":"AA6BA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,WAAW,EACX,YAAY,EACZ,KAAK,SAAS,EACd,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/index.d.ts

@@ -2,9 +2,10 @@ export type { BulkRecordAction, RecordAction, RecordActionContext, } from '../cl
 export type { TriggerContext, WorkflowContext, WorkflowInput, WorkflowOutput, } from '../server/workflow/index.js';
 export { parseScopeString, resolveCapabilities } from '../shared/scopes.js';
 export type { App, AppSettings, Permission } from './app.js';
-export type { ConnectorConnection, ConnectorDefaultMapping, ConnectorEntityDecl, ConnectorExecute, ConnectorExecuteArgs, ConnectorFetchResult, ConnectorFieldCapabilities, ConnectorFieldDecl, ConnectorRecord, ConnectorRelationshipDecl, ConnectorRelationshipTargetRef, ConnectorStreamDecl, ConnectorStreamState, DataConnectorDefinition, } from './data-connectors/index.js';
+export type { ConnectorConnection, ConnectorConnectionField, ConnectorContributingFieldConstant, ConnectorContributingFieldSourceOnly, ConnectorContributingFieldToAppField, ConnectorContributingFieldToTarget, ConnectorContributingMappingField, ConnectorExecute, ConnectorExecuteArgs, ConnectorFetchResult, ConnectorMapping, ConnectorOwnedMappingField, ConnectorRecord, ConnectorStreamDecl, ConnectorStreamState, ContributingConnectorMapping, DataConnectorDefinition, FieldMergeStrategy, OwnedConnectorMapping, } from './data-connectors/index.js';
 export { defineDataConnector } from './data-connectors/index.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 { defineEntity, type EntityDecl } from './entities/index.js';
+export { type AppFieldDefinition, type AppFieldValues, defineField, defineFields, FIELD_TYPES, type FieldCapabilities, type FieldDecl, 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;AAKpC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC3E,YAAY,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC5D,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,eAAe,EACf,yBAAyB,EACzB,8BAA8B,EAC9B,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAEhE,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"}
+{"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;AAKpC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC3E,YAAY,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC5D,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,kCAAkC,EAClC,oCAAoC,EACpC,oCAAoC,EACpC,kCAAkC,EAClC,iCAAiC,EACjC,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,0BAA0B,EAC1B,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAEhE,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEnE,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,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,5 +1,6 @@
 export { parseScopeString, resolveCapabilities } from '../shared/scopes.js';
 export { defineDataConnector } from './data-connectors/index.js';
+export { defineEntity } from './entities/index.js';
 export { defineField, defineFields, FIELD_TYPES, } from './fields/index.js';
 export { Settings } from './settings/index.js';
 export { defineTool, refs, z } from './tools/index.js';

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

@@ -19,7 +19,7 @@ export interface ToolActionContext {
     participants: ToolActionParticipant[];
     entities: ToolActionEntity[];
 }
-export type EntityRefKind = 'contact' | 'company' | 'ticket' | 'article' | 'thread' | 'order' | 'invoice' | 'catalog_item' | 'part' | 'product' | 'build' | 'purchase_order' | 'vendor_bill' | 'gl_account' | 'gl_posting';
+export type EntityRefKind = 'contact' | 'company' | 'ticket' | 'article' | 'thread' | 'order' | 'invoice' | 'line_item' | 'catalog_item' | 'part' | 'product' | 'build' | 'purchase_order' | 'vendor_bill' | 'gl_account';
 export interface ToolConfig {
     readonly requiresConnection?: boolean;
     readonly timeout?: number;

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/util/compile-and-extract-catalog.js

@@ -8,6 +8,14 @@ import { complete, errored, isErrored } from '../errors.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const SDK_ROOT = path.resolve(__dirname, '..', '..');
+const RESERVED_SYSTEM_ATTRIBUTES = new Set([
+    'record_id',
+    'created_at',
+    'updated_at',
+    'created_by_id',
+    'quote_number',
+    'part_quantity_on_hand',
+]);
 export async function compileAndExtractCatalog() {
     const srcDirAbsolute = path.resolve('src');
     const candidates = ['app.ts', 'app.tsx'];
@@ -45,6 +53,7 @@ export async function compileAndExtractCatalog() {
     const SDK_REAL_TOOLS = path.join(SDK_ROOT, 'lib', 'root', 'tools', 'index.js');
     const SDK_REAL_WORKFLOW = path.join(SDK_ROOT, 'lib', 'root', 'workflow', 'index.js');
     const SDK_REAL_FIELDS = path.join(SDK_ROOT, 'lib', 'root', 'fields', 'index.js');
+    const SDK_REAL_ENTITIES = path.join(SDK_ROOT, 'lib', 'root', 'entities', 'index.js');
     const SDK_REAL_DATA_CONNECTORS = path.join(SDK_ROOT, 'lib', 'root', 'data-connectors', 'index.js');
     const stubSdkSubpaths = {
         name: 'auxx-stub-sdk-subpaths',
@@ -58,6 +67,8 @@ export async function compileAndExtractCatalog() {
                     return { path: SDK_REAL_WORKFLOW };
                 if (args.path === '@auxx/sdk/fields')
                     return { path: SDK_REAL_FIELDS };
+                if (args.path === '@auxx/sdk/entities')
+                    return { path: SDK_REAL_ENTITIES };
                 if (args.path === '@auxx/sdk/data-connectors')
                     return { path: SDK_REAL_DATA_CONNECTORS };
                 return { path: args.path, namespace: 'auxx-sdk-stub' };
@@ -124,12 +135,14 @@ export async function compileAndExtractCatalog() {
     const workflowBlocksArr = (app.workflow?.blocks ?? []);
     const workflowTriggersArr = (app.workflow?.triggers ?? []);
     const fieldsArr = (app.fields ?? []);
+    const entitiesArr = (app.entities ?? []);
     const dataConnectorsArr = (app.dataConnectors ?? []);
     if (!toolsArr.length &&
         !toolsetsArr.length &&
         !workflowBlocksArr.length &&
         !workflowTriggersArr.length &&
         !fieldsArr.length &&
+        !entitiesArr.length &&
         !dataConnectorsArr.length) {
         return complete(undefined);
     }
@@ -291,34 +304,102 @@ export async function compileAndExtractCatalog() {
                 : {}),
         });
     }
+    function projectFieldDecl(field) {
+        return {
+            key: field.key,
+            type: field.type,
+            name: field.name,
+            description: field.description,
+            capabilities: field.capabilities,
+            identity: field.identity,
+            options: field.options,
+            addressComponents: field.addressComponents,
+            relationship: field.relationship,
+            calc: field.calc,
+            pii: field.pii,
+        };
+    }
     const cataloguedFields = [];
     const seenFieldKeys = new Set();
+    const identityFieldByTargetEntity = new Map();
     for (const field of fieldsArr) {
-        if (!field?.appFieldKey) {
-            return errored({ code: 'CATALOG_VALIDATION_FAILED', message: 'Field is missing appFieldKey' });
+        if (!field?.key) {
+            return errored({ code: 'CATALOG_VALIDATION_FAILED', message: 'Field is missing key' });
         }
-        const dedupeKey = `${field.targetEntity}:${field.appFieldKey}`;
+        const dedupeKey = `${field.targetEntity}:${field.key}`;
         if (seenFieldKeys.has(dedupeKey)) {
             return errored({
                 code: 'CATALOG_VALIDATION_FAILED',
-                message: `Duplicate field "${field.appFieldKey}" on entity "${field.targetEntity}"`,
+                message: `Duplicate field "${field.key}" on entity "${field.targetEntity}"`,
             });
         }
         seenFieldKeys.add(dedupeKey);
+        if (field.identity) {
+            const existing = identityFieldByTargetEntity.get(field.targetEntity);
+            if (existing) {
+                return errored({
+                    code: 'CATALOG_VALIDATION_FAILED',
+                    message: `More than one identity field targets "${field.targetEntity}" ("${existing}" and "${field.key}") — at most one identity field is allowed per entity`,
+                });
+            }
+            identityFieldByTargetEntity.set(field.targetEntity, field.key);
+        }
         cataloguedFields.push({
-            appFieldKey: field.appFieldKey,
+            ...projectFieldDecl(field),
             scope: field.scope,
             targetEntity: field.targetEntity,
-            type: field.type,
-            name: field.name,
-            description: field.description,
-            options: field.options,
-            relationship: field.relationship,
-            calc: field.calc,
-            capabilities: field.capabilities,
-            identity: field.identity,
         });
     }
+    const cataloguedEntities = [];
+    const entityKeys = new Set(entitiesArr.map((e) => e.key));
+    const entityFieldsByKey = new Map();
+    for (const entity of entitiesArr) {
+        if (!entity?.key) {
+            return errored({ code: 'CATALOG_VALIDATION_FAILED', message: 'Entity is missing a key' });
+        }
+        const fieldMap = new Map();
+        for (const field of entity.fields ?? []) {
+            fieldMap.set(field.key, field);
+            if (field.type === 'RELATIONSHIP' &&
+                field.relationship &&
+                'entityKey' in field.relationship.target) {
+                const targetKey = field.relationship.target.entityKey;
+                if (!entityKeys.has(targetKey)) {
+                    return errored({
+                        code: 'CATALOG_VALIDATION_FAILED',
+                        message: `Entity "${entity.key}" field "${field.key}": relationship target entityKey "${targetKey}" is not a declared entity`,
+                    });
+                }
+            }
+        }
+        entityFieldsByKey.set(entity.key, fieldMap);
+        cataloguedEntities.push({
+            key: entity.key,
+            apiSlug: entity.apiSlug,
+            singular: entity.singular,
+            plural: entity.plural,
+            description: entity.description,
+            icon: entity.icon,
+            color: entity.color,
+            primaryDisplayField: entity.primaryDisplayField,
+            secondaryDisplayField: entity.secondaryDisplayField,
+            avatarField: entity.avatarField,
+            fields: (entity.fields ?? []).map(projectFieldDecl),
+        });
+    }
+    for (const field of fieldsArr) {
+        if (field.type !== 'RELATIONSHIP' || !field.relationship)
+            continue;
+        if (!('entityKey' in field.relationship.target))
+            continue;
+        const targetKey = field.relationship.target.entityKey;
+        if (!entityKeys.has(targetKey)) {
+            return errored({
+                code: 'CATALOG_VALIDATION_FAILED',
+                message: `Field "${field.key}": relationship target entityKey "${targetKey}" is not a declared entity`,
+            });
+        }
+    }
     const cataloguedDataConnectors = [];
     const seenConnectorIds = new Set();
     for (const connector of dataConnectorsArr) {
@@ -355,60 +436,121 @@ export async function compileAndExtractCatalog() {
                 });
             }
         }
+        const streams = [];
         for (const stream of connector.streams ?? []) {
-            for (const mapping of stream.defaultMappings ?? []) {
-                if (mapping.target.mode !== 'contributing')
+            const mappings = [];
+            for (const mapping of stream.mappings ?? []) {
+                const context = `Connector "${connector.id}" stream "${stream.key}" mapping "${mapping.rootPath}"`;
+                if ('entityKey' in mapping.target) {
+                    const entityKey = mapping.target.entityKey;
+                    const fieldMap = entityFieldsByKey.get(entityKey);
+                    if (!fieldMap) {
+                        return errored({
+                            code: 'CATALOG_VALIDATION_FAILED',
+                            message: `${context}: unknown entityKey "${entityKey}" — not a declared entity`,
+                        });
+                    }
+                    const normalizedFields = [];
+                    const ownedFields = (mapping.fields ?? []);
+                    for (const field of ownedFields) {
+                        const entityField = fieldMap.get(field.key);
+                        if (!entityField) {
+                            return errored({
+                                code: 'CATALOG_VALIDATION_FAILED',
+                                message: `${context}: owned field key "${field.key}" is not declared on entity "${entityKey}"`,
+                            });
+                        }
+                        normalizedFields.push({
+                            ...projectFieldDecl(entityField),
+                            sourcePath: field.sourcePath,
+                        });
+                    }
+                    mappings.push({
+                        rootPath: mapping.rootPath,
+                        parentRootPath: mapping.parentRootPath,
+                        linkMode: mapping.linkMode,
+                        relationshipFieldKey: mapping.relationshipFieldKey,
+                        target: { entityKey },
+                        ...(mapping.fields ? { fields: normalizedFields } : {}),
+                    });
                     continue;
-                const { entityKind, fieldBindings, connectionAppFields } = mapping.target;
-                const fieldByKey = new Map(cataloguedFields
-                    .filter((f) => f.targetEntity === entityKind)
-                    .map((f) => [f.appFieldKey, f]));
-                for (const binding of fieldBindings ?? []) {
-                    if (!binding.targetAppField)
-                        continue;
-                    if (!fieldByKey.has(binding.targetAppField)) {
+                }
+                const entityKind = mapping.target.entityKind;
+                const fieldByKey = new Map(cataloguedFields.filter((f) => f.targetEntity === entityKind).map((f) => [f.key, f]));
+                const contributingFields = (mapping.fields ?? []);
+                for (const field of contributingFields) {
+                    if (field.target && RESERVED_SYSTEM_ATTRIBUTES.has(field.target)) {
                         return errored({
                             code: 'CATALOG_VALIDATION_FAILED',
-                            message: `Connector "${connector.id}" stream "${stream.key}": targetAppField "${binding.targetAppField}" is not a declared field on "${entityKind}"`,
+                            message: `${context}: target "${field.target}" is a reserved system attribute and cannot be bound by a contributing field`,
+                        });
+                    }
+                    if (field.appField && !fieldByKey.has(field.appField)) {
+                        return errored({
+                            code: 'CATALOG_VALIDATION_FAILED',
+                            message: `${context}: appField "${field.appField}" is not a declared field on "${entityKind}"`,
+                        });
+                    }
+                    if (field.constant !== undefined) {
+                        if (field.sourcePath) {
+                            return errored({
+                                code: 'CATALOG_VALIDATION_FAILED',
+                                message: `${context}: field with constant ${JSON.stringify(field.constant)} cannot also set a sourcePath`,
+                            });
+                        }
+                        if (!field.target || field.appField) {
+                            return errored({
+                                code: 'CATALOG_VALIDATION_FAILED',
+                                message: `${context}: a constant field needs a target and cannot set appField`,
+                            });
+                        }
+                        if (field.match) {
+                            return errored({
+                                code: 'CATALOG_VALIDATION_FAILED',
+                                message: `${context}: constant field "${field.target}" cannot be a match key, the value is identical on every record`,
+                            });
+                        }
+                    }
+                    else if (!field.sourcePath) {
+                        return errored({
+                            code: 'CATALOG_VALIDATION_FAILED',
+                            message: `${context}: every contributing field needs a sourcePath or a constant`,
                         });
                     }
                 }
-                for (const conn of connectionAppFields ?? []) {
-                    const field = fieldByKey.get(conn.appFieldKey);
+                for (const conn of mapping.connectionFields ?? []) {
+                    const field = fieldByKey.get(conn.appField);
                     if (!field) {
                         return errored({
                             code: 'CATALOG_VALIDATION_FAILED',
-                            message: `Connector "${connector.id}" stream "${stream.key}": connectionAppFields "${conn.appFieldKey}" is not a declared field on "${entityKind}"`,
+                            message: `${context}: connectionFields "${conn.appField}" is not a declared field on "${entityKind}"`,
                         });
                     }
                     if (field.identity) {
                         return errored({
                             code: 'CATALOG_VALIDATION_FAILED',
-                            message: `Connector "${connector.id}" stream "${stream.key}": connectionAppFields "${conn.appFieldKey}" targets an identity field — connection metadata cannot fill an identity field`,
+                            message: `${context}: connectionFields "${conn.appField}" targets an identity field — connection metadata cannot fill an identity field`,
                         });
                     }
                 }
+                mappings.push({
+                    rootPath: mapping.rootPath,
+                    parentRootPath: mapping.parentRootPath,
+                    linkMode: mapping.linkMode,
+                    relationshipFieldKey: mapping.relationshipFieldKey,
+                    target: { entityKind },
+                    fields: mapping.fields,
+                    connectionFields: mapping.connectionFields,
+                });
             }
+            streams.push({
+                key: stream.key,
+                syncMode: stream.syncMode,
+                mappings,
+                exampleRecord: stream.exampleRecord,
+                webhookTrigger: stream.webhookTrigger,
+            });
         }
-        const streams = (connector.streams ?? []).map((stream) => ({
-            key: stream.key,
-            displayFieldKey: stream.displayFieldKey,
-            syncMode: stream.syncMode,
-            fields: Object.entries(stream.fields ?? {}).map(([fieldKey, decl]) => ({
-                fieldKey,
-                sourcePath: decl.sourcePath,
-                type: decl.type,
-                name: decl.name,
-                pii: decl.pii,
-                capabilities: decl.capabilities,
-                options: decl.options,
-                addressComponents: decl.addressComponents,
-                isExternalId: decl.isExternalId,
-            })),
-            defaultMappings: stream.defaultMappings,
-            exampleRecord: stream.exampleRecord,
-            webhookTrigger: stream.webhookTrigger,
-        }));
         cataloguedDataConnectors.push({
             id: connector.id,
             label: connector.label,
@@ -441,6 +583,7 @@ export async function compileAndExtractCatalog() {
         },
         actions: cataloguedActions,
         fields: cataloguedFields,
+        entities: cataloguedEntities,
         dataConnectors: cataloguedDataConnectors,
         events: eventIds,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auxx/sdk",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "CLI tool and SDK for creating Auxx apps",
   "type": "module",
   "bin": {
@@ -46,6 +46,10 @@
       "types": "./lib/root/fields/index.d.ts",
       "import": "./lib/root/fields/index.js"
     },
+    "./entities": {
+      "types": "./lib/root/entities/index.d.ts",
+      "import": "./lib/root/entities/index.js"
+    },
     "./data-connectors": {
       "types": "./lib/root/data-connectors/index.d.ts",
       "import": "./lib/root/data-connectors/index.js"