@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/AiProvider.ts

@@ -0,0 +1,255 @@
+/**
+ * AI provider definitions for model authentication.
+ *
+ * AI providers share provider metadata and auth methods with Tools providers,
+ * but cannot contribute actions, triggers, or groups. Their identifier is a
+ * stable key matched exactly against Pi's `Model.provider` value.
+ *
+ * @since 0.0.0
+ */
+import type { Pipeable } from "effect";
+import { Function as Func, Predicate, Schema } from "effect";
+
+import type * as AuthMethod from "./AuthMethod.ts";
+import type * as AuthMethodBinding from "./AuthMethodBinding.ts";
+import { assertNoDuplicateAuthMethodIdentifiers } from "./internal/auth-runtime.ts";
+import { appendElements } from "./internal/collection-utils.ts";
+import { validateIdentifier } from "./internal/identifier.ts";
+import { PipeableProto } from "./internal/proto.ts";
+import type { Category } from "./Plugin.ts";
+
+/** @since 0.0.0 @category type ids */
+export const TypeId = "@dual-os/sdk/AiProvider" as const;
+/** @since 0.0.0 @category type ids */
+export type TypeId = typeof TypeId;
+
+/** @since 0.0.0 @category type-level */
+export interface Any extends Pipeable.Pipeable {
+  readonly [TypeId]: TypeId;
+  readonly identifier: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly iconUrl: string | undefined;
+  readonly iconUrlDark: string | undefined;
+  readonly categories: readonly Category[];
+  readonly homepageUrl: string | undefined;
+  readonly docsUrl: string | undefined;
+  readonly authMethods: readonly AuthMethod.Any[];
+  readonly resolveRuntimeConfig: unknown;
+}
+
+/** @since 0.0.0 @category models */
+export const RuntimeConfig = Schema.Struct({
+  apiKey: Schema.optional(Schema.String),
+  baseUrl: Schema.optional(Schema.String),
+  env: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  headers: Schema.optional(Schema.Record(Schema.String, Schema.NullOr(Schema.String))),
+});
+
+/** @since 0.0.0 @category models */
+export type RuntimeConfig = typeof RuntimeConfig.Type;
+
+/** @since 0.0.0 @category models */
+export interface RuntimeModel {
+  readonly id: string;
+  readonly baseUrl: string;
+}
+
+/** @since 0.0.0 @category models */
+export interface RuntimeConfigResolverInput<Methods extends readonly AuthMethod.Any[]> {
+  readonly model: RuntimeModel;
+  readonly binding: AuthMethodBinding.BindingFor<Methods>;
+}
+
+/** @since 0.0.0 @category models */
+export type RuntimeConfigResolver<Methods extends readonly AuthMethod.Any[]> = (
+  input: RuntimeConfigResolverInput<Methods>,
+) => RuntimeConfig;
+
+/** @since 0.0.0 @category models */
+export interface AiProviderOptions<Identifier extends string = string> {
+  readonly identifier: Identifier;
+  readonly name?: string;
+  readonly description?: string;
+  readonly iconUrl?: string;
+  readonly iconUrlDark?: string;
+  readonly categories?: readonly Category[];
+  readonly homepageUrl?: string;
+  readonly docsUrl?: string;
+}
+
+/** @since 0.0.0 @category models */
+export interface AiProvider<
+  out Identifier extends string = string,
+  out AuthMethods extends readonly AuthMethod.Any[] = readonly [],
+>
+  extends Pipeable.Pipeable {
+  readonly [TypeId]: TypeId;
+  readonly identifier: Identifier;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly iconUrl: string | undefined;
+  readonly iconUrlDark: string | undefined;
+  readonly categories: readonly Category[];
+  readonly homepageUrl: string | undefined;
+  readonly docsUrl: string | undefined;
+  readonly authMethods: AuthMethods;
+  readonly resolveRuntimeConfig: RuntimeConfigResolver<AuthMethods> | undefined;
+}
+
+/** @since 0.0.0 @category type-level */
+export type AddAuthMethods<Self extends Any, AddedMethods extends readonly AuthMethod.Any[]> =
+  Self extends AiProvider<infer Identifier, infer AuthMethods>
+    ? AiProvider<Identifier, readonly [...AuthMethods, ...AddedMethods]>
+    : never;
+
+const optionsFromProvider = (provider: Any): AiProviderOptions => ({
+  identifier: provider.identifier,
+  ...(provider.name === undefined ? {} : { name: provider.name }),
+  ...(provider.description === undefined ? {} : { description: provider.description }),
+  ...(provider.iconUrl === undefined ? {} : { iconUrl: provider.iconUrl }),
+  ...(provider.iconUrlDark === undefined ? {} : { iconUrlDark: provider.iconUrlDark }),
+  ...(provider.categories.length === 0 ? {} : { categories: provider.categories }),
+  ...(provider.homepageUrl === undefined ? {} : { homepageUrl: provider.homepageUrl }),
+  ...(provider.docsUrl === undefined ? {} : { docsUrl: provider.docsUrl }),
+});
+
+const Proto = { ...PipeableProto, [TypeId]: TypeId };
+
+const makeProvider = <Identifier extends string, AuthMethods extends readonly AuthMethod.Any[]>(
+  options: AiProviderOptions<Identifier>,
+  authMethods: AuthMethods,
+  resolveRuntimeConfig?: RuntimeConfigResolver<AuthMethods>,
+): AiProvider<Identifier, AuthMethods> => {
+  validateIdentifier("provider", options.identifier);
+  assertNoDuplicateAuthMethodIdentifiers(options.identifier, authMethods);
+
+  return Object.assign(Object.create(Proto), {
+    authMethods,
+    categories: options.categories ?? [],
+    description: options.description,
+    docsUrl: options.docsUrl,
+    homepageUrl: options.homepageUrl,
+    iconUrl: options.iconUrl,
+    iconUrlDark: options.iconUrlDark,
+    identifier: options.identifier,
+    name: options.name,
+    resolveRuntimeConfig,
+  });
+};
+
+/** @since 0.0.0 @category constructors */
+export const make = <const Identifier extends string>(
+  identifier: Identifier,
+): AiProvider<Identifier> => makeProvider({ identifier }, [] as const);
+
+/** @since 0.0.0 @category registry */
+export const registryId = (identifier: string): string => `ai/${identifier}`;
+
+/** @since 0.0.0 @category guards */
+export const isAiProvider = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
+
+const withOption = <P extends AiProvider<any, any>>(
+  provider: P,
+  options: Partial<AiProviderOptions>,
+): P =>
+  makeProvider(
+    { ...optionsFromProvider(provider), ...options },
+    provider.authMethods,
+    provider.resolveRuntimeConfig,
+  ) as P;
+
+/** @since 0.0.0 @category combinators */
+export const withName: {
+  (name: string): <P extends AiProvider<any, any>>(provider: P) => P;
+  <P extends AiProvider<any, any>>(provider: P, name: string): P;
+} = Func.dual(2, (provider: AiProvider<any, any>, name: string) => withOption(provider, { name }));
+
+/** @since 0.0.0 @category combinators */
+export const withDescription: {
+  (description: string): <P extends AiProvider<any, any>>(provider: P) => P;
+  <P extends AiProvider<any, any>>(provider: P, description: string): P;
+} = Func.dual(2, (provider: AiProvider<any, any>, description: string) =>
+  withOption(provider, { description }),
+);
+
+/** @since 0.0.0 @category combinators */
+export const withIconUrl: {
+  (iconUrl: string): <P extends AiProvider<any, any>>(provider: P) => P;
+  <P extends AiProvider<any, any>>(provider: P, iconUrl: string): P;
+} = Func.dual(2, (provider: AiProvider<any, any>, iconUrl: string) =>
+  withOption(provider, { iconUrl }),
+);
+
+/** @since 0.0.0 @category combinators */
+export const withIconUrlDark: {
+  (iconUrlDark: string): <P extends AiProvider<any, any>>(provider: P) => P;
+  <P extends AiProvider<any, any>>(provider: P, iconUrlDark: string): P;
+} = Func.dual(2, (provider: AiProvider<any, any>, iconUrlDark: string) =>
+  withOption(provider, { iconUrlDark }),
+);
+
+/** @since 0.0.0 @category combinators */
+export const withCategories: {
+  (categories: readonly Category[]): <P extends AiProvider<any, any>>(provider: P) => P;
+  <P extends AiProvider<any, any>>(provider: P, categories: readonly Category[]): P;
+} = Func.dual(2, (provider: AiProvider<any, any>, categories: readonly Category[]) =>
+  withOption(provider, { categories: [...categories] }),
+);
+
+/** @since 0.0.0 @category combinators */
+export const withHomepageUrl: {
+  (homepageUrl: string): <P extends AiProvider<any, any>>(provider: P) => P;
+  <P extends AiProvider<any, any>>(provider: P, homepageUrl: string): P;
+} = Func.dual(2, (provider: AiProvider<any, any>, homepageUrl: string) =>
+  withOption(provider, { homepageUrl }),
+);
+
+/** @since 0.0.0 @category combinators */
+export const withDocsUrl: {
+  (docsUrl: string): <P extends AiProvider<any, any>>(provider: P) => P;
+  <P extends AiProvider<any, any>>(provider: P, docsUrl: string): P;
+} = Func.dual(2, (provider: AiProvider<any, any>, docsUrl: string) =>
+  withOption(provider, { docsUrl }),
+);
+
+/** @since 0.0.0 @category combinators */
+export const withAuthMethods: {
+  <const AddedMethods extends readonly AuthMethod.Any[]>(
+    methods: AddedMethods,
+  ): <Self extends Any>(provider: Self) => AddAuthMethods<Self, AddedMethods>;
+  <Self extends Any, const AddedMethods extends readonly AuthMethod.Any[]>(
+    provider: Self,
+    methods: AddedMethods,
+  ): AddAuthMethods<Self, AddedMethods>;
+} = Func.dual(2, (provider: Any, methods: readonly AuthMethod.Any[]) => {
+  if (provider.resolveRuntimeConfig !== undefined) {
+    throw new Error(
+      `AI provider "${provider.identifier}" must declare auth methods before its runtime config`,
+    );
+  }
+  return makeProvider(optionsFromProvider(provider), appendElements(provider.authMethods, methods));
+});
+
+/** @since 0.0.0 @category combinators */
+export const withAuthMethod: {
+  <const AddedMethod extends AuthMethod.Any>(
+    method: AddedMethod,
+  ): <Self extends Any>(provider: Self) => AddAuthMethods<Self, readonly [AddedMethod]>;
+  <Self extends Any, const AddedMethod extends AuthMethod.Any>(
+    provider: Self,
+    method: AddedMethod,
+  ): AddAuthMethods<Self, readonly [AddedMethod]>;
+} = Func.dual(2, (provider: Any, method: AuthMethod.Any) =>
+  withAuthMethods(provider, [method] as const),
+);
+
+/** @since 0.0.0 @category combinators */
+export const withRuntimeConfig: {
+  <Self extends Any>(resolve: RuntimeConfigResolver<Self["authMethods"]>): (provider: Self) => Self;
+  <Self extends Any>(provider: Self, resolve: RuntimeConfigResolver<Self["authMethods"]>): Self;
+} = Func.dual(
+  2,
+  (provider: AiProvider<any, any>, resolve: RuntimeConfigResolver<readonly AuthMethod.Any[]>) =>
+    makeProvider(optionsFromProvider(provider), provider.authMethods, resolve),
+);