[Feature]: Types registry support

[kfirstri]

Summary

We want to give developers the option to use the entities, agents and functions they've created when calling the sdk.
This PR adds Type Registries and can be augmented from outside of the SDK.

base44/cli#199 This PR in CLI generates types

[claude]

Claude finished @kfirstri's task —— View job

---

PR Review: Types Registry Support

Review Checklist

• Analyze the type registry implementation approach
• Review src/index.ts changes
• Review src/modules/agents.types.ts changes
• Review src/modules/entities.types.ts changes
• Review src/modules/functions.types.ts changes
• Check for TypeScript best practices
• Assess potential bugs or issues
• Evaluate performance considerations
• Review security concerns
• Check test coverage needs

---

Summary

This PR implements a type registry system that allows developers to augment the SDK's types with their custom entities, agents, and functions. The implementation uses TypeScript's declaration merging feature to provide type-safe autocomplete and better developer experience.

Code Quality and Best Practices ✅

The implementation follows excellent TypeScript practices:

1. Smart use of conditional types: The registry pattern uses keyof Registry extends never to fall back to string when not augmented
2. Clear documentation: Each registry interface has comprehensive JSDoc comments with examples
3. Consistent patterns: All three registries (entities, agents, functions) follow the same implementation approach
4. Backward compatibility: The fallback to string ensures existing code continues to work

Potential Issues 🔍

1. Entities Module Type Declaration Location

In /tests/unit/entities.test.ts:16-20, the test shows module augmentation:

declare module "../../src/modules/entities.types.ts" {
  interface EntitiesModule {
    Todo: EntityHandler<Todo>;
  }
}

This augments EntitiesModule instead of EntityTypeRegistry. The correct pattern should be:

declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Todo: Todo;
  }
}

2. Registry Naming Consistency

The registries use different value types:

• EntityTypeRegistry: Maps to entity types (Task: { title: string; ... })
• AgentNameRegistry & FunctionNameRegistry: Maps to true (support_agent: true)

Consider using consistent patterns. Either all map to types or all map to true.

Performance Considerations ⚡

The type registry implementation has zero runtime overhead as it's purely a TypeScript compile-time feature. The conditional types are resolved during compilation, resulting in no performance impact.

Security Concerns 🔒

No security issues identified. The implementation:

• Is purely type-level with no runtime code changes
• Doesn't expose any internal APIs
• Maintains existing access control patterns

Test Coverage 🧪

The existing test in entities.test.ts demonstrates module augmentation, but the PR could benefit from:

1. Type test files: Add .test-d.ts files to verify type inference works correctly
2. Documentation tests: Ensure the JSDoc examples compile correctly
3. Integration examples: Show how generated type files would work with the SDK

Suggested Test Example:

// types.test-d.ts
import { expectType } from 'tsd';
import { createClient } from '@base44/sdk';

// Test that augmentation works
declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Task: { id: string; title: string; completed: boolean };
  }
  interface AgentNameRegistry {
    'support-agent': true;
  }
  interface FunctionNameRegistry {
    calculateTotal: true;
  }
}

const client = createClient({ appId: 'test', serverUrl: 'test' });

// Should have autocomplete for Task
expectType<{ id: string; title: string; completed: boolean }>(
  await client.entities.Task.get('123')
);

// Should have autocomplete for agent names
await client.agents.createConversation({
  agent_name: 'support-agent' // ✅ Type-safe
});

// Should have autocomplete for function names
await client.functions.invoke('calculateTotal', {}); // ✅ Type-safe

Recommendations 💡

1. Add a types generation guide: Document how developers should generate their types.d.ts files
2. Consider a CLI tool: A @base44/cli package could generate type declarations from the app's schema
3. Add runtime validation: While types help at compile time, runtime validation would catch mismatches
4. Version compatibility: Document which SDK versions support type augmentation

Overall, this is a well-implemented feature that significantly improves the developer experience. The code is clean, follows TypeScript best practices, and maintains backward compatibility. With the minor suggestions above, this will be an excellent addition to the SDK.

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.18-pr.117.353547f

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.18-pr.117.353547f"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.18-pr.117.353547f"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.18-pr.117.353547f
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[claude]

Claude finished @kfirstri's task —— View job

---

PR Review: Types Registry Support

I've reviewed the implementation of the type registry system in this PR. Here's my comprehensive feedback:

Overview

This PR implements a clean type registry system that allows developers to augment the SDK's types with their custom entities, agents, and functions. The approach leverages TypeScript's declaration merging to provide type-safe autocomplete and better developer experience.

Code Quality and Best Practices ✅

The implementation demonstrates excellent TypeScript practices:

1. Smart use of conditional types: The pattern keyof Registry extends never ? string : keyof Registry elegantly falls back to string when the registry isn't augmented, maintaining backward compatibility.

2. Clear documentation: Each registry interface includes comprehensive JSDoc comments explaining the purpose and usage.

3. Consistent implementation: All three registries follow the same pattern, making the API predictable.

4. Type exports: All necessary types are properly exported in src/index.ts (lines 39, 77, 82).

Potential Issues 🔍

1. Test File Module Augmentation Pattern

In tests/unit/entities.test.ts (lines 16-20), I notice an inconsistency:

declare module "../../src/modules/entities.types.ts" {
  interface EntitiesModule {
    Todo: EntityHandler<Todo>;
  }
}

This augments EntitiesModule directly rather than EntityTypeRegistry. Based on the implementation, the correct pattern should be:

declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Todo: Todo; // Just the type, not the handler
  }
}

The EntitiesModule type will automatically create the EntityHandler<Todo> wrapper through the TypedEntitiesModule type mapping.

2. Registry Value Type Inconsistency

The registries use different value patterns:

• EntityTypeRegistry: Maps to entity types (e.g., Todo: { id: string; title: string; ... })
• AgentNameRegistry & FunctionNameRegistry: Would map to true (e.g., 'support-agent': true)

This inconsistency might be confusing. Consider documenting why agents/functions use boolean markers while entities use full type definitions.

Performance Considerations ⚡

Zero runtime overhead - The type registry system is purely compile-time TypeScript. The conditional types are resolved during compilation, resulting in no performance impact at runtime.

Security Concerns 🔒

No security issues identified. The implementation:

• Is purely type-level with no runtime code execution
• Doesn't expose any internal APIs or data
• Maintains existing security boundaries

Test Coverage Suggestions 🧪

The current test demonstrates the concept but could benefit from:

1. Type-level tests: Add .test-d.ts files using a library like tsd to verify type inference:

// types.test-d.ts
import { expectType } from 'tsd';
import { createClient } from '@base44/sdk';

declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Task: { id: string; title: string; completed: boolean };
  }
  interface AgentNameRegistry {
    'support-agent': true;
  }
  interface FunctionNameRegistry {
    calculateTotal: true;
  }
}

const client = createClient({ appId: 'test', serverUrl: 'test' });

// These should have proper type inference
expectType<{ id: string; title: string; completed: boolean }>(
  await client.entities.Task.get('123')
);

await client.agents.createConversation({
  agent_name: 'support-agent' // Should autocomplete
});

await client.functions.invoke('calculateTotal', {}); // Should autocomplete

2. Documentation tests: Ensure JSDoc examples are valid TypeScript.

3. Integration examples: Show how the generated type files from the CLI would work.

Recommendations 💡

1. Type Generation Guide: Add documentation explaining how developers should structure their types.d.ts files and where to place them.

2. Migration Path: Consider documenting how existing projects can adopt this feature.

3. Error Messages: The fallback to string is smooth, but consider if there's a way to provide helpful error messages when types aren't properly augmented.

4. Registry Documentation: Add examples in the JSDoc showing the exact augmentation syntax users should use.

Summary

This is a well-implemented feature that significantly improves developer experience without breaking changes. The code is clean, follows TypeScript best practices, and maintains backward compatibility. The minor suggestions above would make it even more robust and user-friendly.

Great work on this implementation! 🎉

[claude]

Claude finished @kfirstri's task —— View job

---

PR Review: Types Registry Support

I've reviewed the implementation of the type registry system in this PR. Here's my comprehensive feedback:

Overview

This PR implements a clean type registry system that allows developers to augment the SDK's types with their custom entities, agents, and functions. The approach leverages TypeScript's declaration merging to provide type-safe autocomplete and better developer experience.

Code Quality and Best Practices ✅

The implementation demonstrates excellent TypeScript practices:

1. Smart use of conditional types: The pattern keyof Registry extends never ? string : keyof Registry elegantly falls back to string when the registry isn't augmented, maintaining backward compatibility.

2. Clear documentation: Each registry interface includes comprehensive JSDoc comments explaining the purpose and usage.

3. Consistent implementation: All three registries follow the same pattern, making the API predictable.

4. Type exports: All necessary types are properly exported in src/index.ts (lines 39, 77, 82).

Potential Issues 🔍

1. Test File Module Augmentation Pattern

In tests/unit/entities.test.ts (lines 16-20), I notice an inconsistency:

declare module "../../src/modules/entities.types.ts" {
  interface EntitiesModule {
    Todo: EntityHandler<Todo>;
  }
}

This augments EntitiesModule directly rather than EntityTypeRegistry. Based on the implementation, the correct pattern should be:

declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Todo: Todo; // Just the type, not the handler
  }
}

The EntitiesModule type will automatically create the EntityHandler<Todo> wrapper through the TypedEntitiesModule type mapping.

2. Registry Value Type Inconsistency

The registries use different value patterns:

• EntityTypeRegistry: Maps to entity types (e.g., Todo: { id: string; title: string; ... })
• AgentNameRegistry & FunctionNameRegistry: Would map to true (e.g., 'support-agent': true)

This inconsistency might be confusing. Consider documenting why agents/functions use boolean markers while entities use full type definitions.

Performance Considerations ⚡

Zero runtime overhead - The type registry system is purely compile-time TypeScript. The conditional types are resolved during compilation, resulting in no performance impact at runtime.

Security Concerns 🔒

No security issues identified. The implementation:

• Is purely type-level with no runtime code execution
• Doesn't expose any internal APIs or data
• Maintains existing security boundaries

Test Coverage Suggestions 🧪

The current test demonstrates the concept but could benefit from:

1. Type-level tests: Add .test-d.ts files using a library like tsd to verify type inference:

// types.test-d.ts
import { expectType } from 'tsd';
import { createClient } from '@base44/sdk';

declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Task: { id: string; title: string; completed: boolean };
  }
  interface AgentNameRegistry {
    'support-agent': true;
  }
  interface FunctionNameRegistry {
    calculateTotal: true;
  }
}

const client = createClient({ appId: 'test', serverUrl: 'test' });

// These should have proper type inference
expectType<{ id: string; title: string; completed: boolean }>(
  await client.entities.Task.get('123')
);

await client.agents.createConversation({
  agent_name: 'support-agent' // Should autocomplete
});

await client.functions.invoke('calculateTotal', {}); // Should autocomplete

2. Documentation tests: Ensure JSDoc examples are valid TypeScript.

3. Integration examples: Show how the generated type files from the CLI would work.

Recommendations 💡

1. Type Generation Guide: Add documentation explaining how developers should structure their types.d.ts files and where to place them.

2. Migration Path: Consider documenting how existing projects can adopt this feature.

3. Error Messages: The fallback to string is smooth, but consider if there's a way to provide helpful error messages when types aren't properly augmented.

4. Registry Documentation: Add examples in the JSDoc showing the exact augmentation syntax users should use.

Summary

This is a well-implemented feature that significantly improves developer experience without breaking changes. The code is clean, follows TypeScript best practices, and maintains backward compatibility. The minor suggestions above would make it even more robust and user-friendly.

Great work on this implementation! 🎉

[claude]

Claude finished @kfirstri's task —— View job

---

PR Review: Types Registry Support

Review Checklist

• Read and analyze the type registry implementation
• Review src/index.ts changes
• Review src/modules/agents.types.ts changes
• Review src/modules/entities.types.ts changes
• Review src/modules/functions.types.ts changes
• Check for TypeScript best practices
• Assess potential bugs or issues
• Evaluate performance considerations
• Review security concerns
• Check test coverage needs
• Provide comprehensive feedback

---

Summary

This PR implements a type registry system that allows developers to augment the SDK's types with their custom entities, agents, and functions. The implementation uses TypeScript's declaration merging feature to provide type-safe autocomplete and better developer experience.

Code Quality and Best Practices ✅

The implementation follows excellent TypeScript practices:

1. Smart use of conditional types: The registry pattern uses keyof Registry extends never to fall back to string when not augmented
2. Clear documentation: Each registry interface has comprehensive JSDoc comments with examples
3. Consistent patterns: All three registries (entities, agents, functions) follow the same implementation approach
4. Backward compatibility: The fallback to string ensures existing code continues to work

Potential Issues 🔍

1. Entities Module Type Declaration Location

In /tests/unit/entities.test.ts:16-20, the test shows module augmentation:

declare module "../../src/modules/entities.types.ts" {
  interface EntitiesModule {
    Todo: EntityHandler<Todo>;
  }
}

This augments EntitiesModule instead of EntityTypeRegistry. The correct pattern should be:

declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Todo: Todo;
  }
}

2. Registry Naming Consistency

The registries use different value types:

• EntityTypeRegistry: Maps to entity types (Task: { title: string; ... })
• AgentNameRegistry & FunctionNameRegistry: Maps to true (support_agent: true)

Consider using consistent patterns. Either all map to types or all map to true.

Performance Considerations ⚡

The type registry implementation has zero runtime overhead as it's purely a TypeScript compile-time feature. The conditional types are resolved during compilation, resulting in no performance impact.

Security Concerns 🔒

No security issues identified. The implementation:

• Is purely type-level with no runtime code changes
• Doesn't expose any internal APIs
• Maintains existing access control patterns

Test Coverage 🧪

The existing test in entities.test.ts demonstrates module augmentation, but the PR could benefit from:

1. Type test files: Add .test-d.ts files to verify type inference works correctly
2. Documentation tests: Ensure the JSDoc examples compile correctly
3. Integration examples: Show how generated type files would work with the SDK

Suggested Test Example:

// types.test-d.ts
import { expectType } from 'tsd';
import { createClient } from '@base44/sdk';

// Test that augmentation works
declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Task: { id: string; title: string; completed: boolean };
  }
  interface AgentNameRegistry {
    'support-agent': true;
  }
  interface FunctionNameRegistry {
    calculateTotal: true;
  }
}

const client = createClient({ appId: 'test', serverUrl: 'test' });

// Should have autocomplete for Task
expectType<{ id: string; title: string; completed: boolean }>(
  await client.entities.Task.get('123')
);

// Should have autocomplete for agent names
await client.agents.createConversation({
  agent_name: 'support-agent' // ✅ Type-safe
});

// Should have autocomplete for function names
await client.functions.invoke('calculateTotal', {}); // ✅ Type-safe

Recommendations 💡

1. Add a types generation guide: Document how developers should generate their types.d.ts files
2. Consider a CLI tool: A @base44/cli package could generate type declarations from the app's schema
3. Add runtime validation: While types help at compile time, runtime validation would catch mismatches
4. Version compatibility: Document which SDK versions support type augmentation

Overall, this is a well-implemented feature that significantly improves the developer experience. The code is clean, follows TypeScript best practices, and maintains backward compatibility. With the minor suggestions above, this will be an excellent addition to the SDK.

[claude]

Claude finished @kfirstri's task —— View job

---

PR Review: Types Registry Support

Review Checklist

• Analyze the type registry implementation approach
• Review src/index.ts changes
• Review src/modules/agents.types.ts changes
• Review src/modules/entities.types.ts changes
• Review src/modules/functions.types.ts changes
• Check for TypeScript best practices
• Assess potential bugs or issues
• Evaluate performance considerations
• Review security concerns
• Check test coverage needs

---

Summary

This PR implements a type registry system that allows developers to augment the SDK's types with their custom entities, agents, and functions. The implementation uses TypeScript's declaration merging feature to provide type-safe autocomplete and better developer experience.

Code Quality and Best Practices ✅

The implementation follows excellent TypeScript practices:

1. Smart use of conditional types: The registry pattern uses keyof Registry extends never to fall back to string when not augmented
2. Clear documentation: Each registry interface has comprehensive JSDoc comments with examples
3. Consistent patterns: All three registries (entities, agents, functions) follow the same implementation approach
4. Backward compatibility: The fallback to string ensures existing code continues to work

Potential Issues 🔍

1. Entities Module Type Declaration Location

In /tests/unit/entities.test.ts:16-20, the test shows module augmentation:

declare module "../../src/modules/entities.types.ts" {
  interface EntitiesModule {
    Todo: EntityHandler<Todo>;
  }
}

This augments EntitiesModule instead of EntityTypeRegistry. The correct pattern should be:

declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Todo: Todo;
  }
}

2. Registry Naming Consistency

The registries use different value types:

• EntityTypeRegistry: Maps to entity types (Task: { title: string; ... })
• AgentNameRegistry & FunctionNameRegistry: Maps to true (support_agent: true)

Consider using consistent patterns. Either all map to types or all map to true.

Performance Considerations ⚡

The type registry implementation has zero runtime overhead as it's purely a TypeScript compile-time feature. The conditional types are resolved during compilation, resulting in no performance impact.

Security Concerns 🔒

No security issues identified. The implementation:

• Is purely type-level with no runtime code changes
• Doesn't expose any internal APIs
• Maintains existing access control patterns

Test Coverage 🧪

The existing test in entities.test.ts demonstrates module augmentation, but the PR could benefit from:

1. Type test files: Add .test-d.ts files to verify type inference works correctly
2. Documentation tests: Ensure the JSDoc examples compile correctly
3. Integration examples: Show how generated type files would work with the SDK

Suggested Test Example:

// types.test-d.ts
import { expectType } from 'tsd';
import { createClient } from '@base44/sdk';

// Test that augmentation works
declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Task: { id: string; title: string; completed: boolean };
  }
  interface AgentNameRegistry {
    'support-agent': true;
  }
  interface FunctionNameRegistry {
    calculateTotal: true;
  }
}

const client = createClient({ appId: 'test', serverUrl: 'test' });

// Should have autocomplete for Task
expectType<{ id: string; title: string; completed: boolean }>(
  await client.entities.Task.get('123')
);

// Should have autocomplete for agent names
await client.agents.createConversation({
  agent_name: 'support-agent' // ✅ Type-safe
});

// Should have autocomplete for function names
await client.functions.invoke('calculateTotal', {}); // ✅ Type-safe

Recommendations 💡

1. Add a types generation guide: Document how developers should generate their types.d.ts files
2. Consider a CLI tool: A @base44/cli package could generate type declarations from the app's schema
3. Add runtime validation: While types help at compile time, runtime validation would catch mismatches
4. Version compatibility: Document which SDK versions support type augmentation

Overall, this is a well-implemented feature that significantly improves the developer experience. The code is clean, follows TypeScript best practices, and maintains backward compatibility. With the minor suggestions above, this will be an excellent addition to the SDK.

[claude]

Claude finished @kfirstri's task —— View job

---

PR Review: Types Registry Support

I've reviewed the implementation of the type registry system in this PR. Here's my comprehensive feedback:

Overview

This PR implements a clean type registry system that allows developers to augment the SDK's types with their custom entities, agents, and functions. The approach leverages TypeScript's declaration merging to provide type-safe autocomplete and better developer experience.

Code Quality and Best Practices ✅

The implementation demonstrates excellent TypeScript practices:

1. Smart use of conditional types: The pattern keyof Registry extends never ? string : keyof Registry elegantly falls back to string when the registry isn't augmented, maintaining backward compatibility.

2. Clear documentation: Each registry interface includes comprehensive JSDoc comments explaining the purpose and usage.

3. Consistent implementation: All three registries follow the same pattern, making the API predictable.

4. Type exports: All necessary types are properly exported in src/index.ts (lines 39, 77, 82).

Potential Issues 🔍

1. Test File Module Augmentation Pattern

In tests/unit/entities.test.ts (lines 16-20), I notice an inconsistency:

declare module "../../src/modules/entities.types.ts" {
  interface EntitiesModule {
    Todo: EntityHandler<Todo>;
  }
}

This augments EntitiesModule directly rather than EntityTypeRegistry. Based on the implementation, the correct pattern should be:

declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Todo: Todo; // Just the type, not the handler
  }
}

The EntitiesModule type will automatically create the EntityHandler<Todo> wrapper through the TypedEntitiesModule type mapping.

2. Registry Value Type Inconsistency

The registries use different value patterns:

• EntityTypeRegistry: Maps to entity types (e.g., Todo: { id: string; title: string; ... })
• AgentNameRegistry & FunctionNameRegistry: Would map to true (e.g., 'support-agent': true)

This inconsistency might be confusing. Consider documenting why agents/functions use boolean markers while entities use full type definitions.

Performance Considerations ⚡

Zero runtime overhead - The type registry system is purely compile-time TypeScript. The conditional types are resolved during compilation, resulting in no performance impact at runtime.

Security Concerns 🔒

No security issues identified. The implementation:

• Is purely type-level with no runtime code execution
• Doesn't expose any internal APIs or data
• Maintains existing security boundaries

Test Coverage Suggestions 🧪

The current test demonstrates the concept but could benefit from:

1. Type-level tests: Add .test-d.ts files using a library like tsd to verify type inference:

// types.test-d.ts
import { expectType } from 'tsd';
import { createClient } from '@base44/sdk';

declare module '@base44/sdk' {
  interface EntityTypeRegistry {
    Task: { id: string; title: string; completed: boolean };
  }
  interface AgentNameRegistry {
    'support-agent': true;
  }
  interface FunctionNameRegistry {
    calculateTotal: true;
  }
}

const client = createClient({ appId: 'test', serverUrl: 'test' });

// These should have proper type inference
expectType<{ id: string; title: string; completed: boolean }>(
  await client.entities.Task.get('123')
);

await client.agents.createConversation({
  agent_name: 'support-agent' // Should autocomplete
});

await client.functions.invoke('calculateTotal', {}); // Should autocomplete

2. Documentation tests: Ensure JSDoc examples are valid TypeScript.

3. Integration examples: Show how the generated type files from the CLI would work.

Recommendations 💡

1. Type Generation Guide: Add documentation explaining how developers should structure their types.d.ts files and where to place them.

2. Migration Path: Consider documenting how existing projects can adopt this feature.

3. Error Messages: The fallback to string is smooth, but consider if there's a way to provide helpful error messages when types aren't properly augmented.

4. Registry Documentation: Add examples in the JSDoc showing the exact augmentation syntax users should use.

Summary

This is a well-implemented feature that significantly improves developer experience without breaking changes. The code is clean, follows TypeScript best practices, and maintains backward compatibility. The minor suggestions above would make it even more robust and user-friendly.

Great work on this implementation! 🎉