@withloops.ai/contracts 0.3.0 → 0.4.0

package/src/trust.ts

@@ -122,6 +122,29 @@ export const SecretRef = z.object({
 });
 export type SecretRef = z.infer<typeof SecretRef>;
 
+/**
+ * The developer's OAuth client secret for their own service is stored once per app under this reserved install id,
+ * in the app owner's workspace: `{ installId: APP_CLIENT_INSTALL_ID, workspaceId: app.ownerWorkspaceId, appId, name: 'oauth_client_secret' }`.
+ * Uninstall never deletes it; only deleting the app does. Added in 0.3.1.
+ */
+export const APP_CLIENT_INSTALL_ID = 'ins_appclient' as const;
+export const APP_CLIENT_SECRET_NAME = 'oauth_client_secret' as const;
+export function appClientSecretRef(appId: string, ownerWorkspaceId: string): SecretRef {
+  return { installId: APP_CLIENT_INSTALL_ID, workspaceId: ownerWorkspaceId, appId, name: APP_CLIENT_SECRET_NAME };
+}
+
+/** Engine-side code exchange for an app connecting OUT (the handoff at api.thesoogroup.com/oauth/callback). Added in 0.3.1. */
+export const OAuthCodeExchange = z.object({
+  install: SecretRef.omit({ name: true }),
+  ownerWorkspaceId: WorkspaceId,
+  tokenUrl: z.string().url(),
+  clientId: z.string().min(1),
+  code: z.string().min(1),
+  codeVerifier: z.string().min(43).max(128).optional(),
+  redirectUri: z.string().url(),
+});
+export type OAuthCodeExchange = z.infer<typeof OAuthCodeExchange>;
+
 /** What anyone outside the engine may see about a secret: never the value. */
 export const SecretInfo = z.object({
   name: SecretName,
@@ -156,4 +179,6 @@ export interface EngineVaultRpc {
   listSecrets(installId: string): Promise<SecretInfo[]>;
   /** Uninstall calls this; returns how many rows went. */
   deleteSecrets(installId: string): Promise<{ deleted: number }>;
+  /** Reads the app's client secret, POSTs to tokenUrl, stores access/refresh tokens for the install itself. Values never come back. Added in 0.3.1. */
+  exchangeOAuthCode(input: OAuthCodeExchange): Promise<{ ok: true; expiresAt: string | null } | { ok: false; error: string }>;
 }