@withloops.ai/contracts 0.3.0 → 0.3.1

package/dist/manifest.d.ts

@@ -16,6 +16,7 @@ export declare const SyncAuth: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"oauth2">;
     authorizeUrl: z.ZodURL;
     tokenUrl: z.ZodURL;
+    clientId: z.ZodOptional<z.ZodString>;
     scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
     refresh: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
@@ -127,6 +128,7 @@ export declare const SyncManifest: z.ZodObject<{
         type: z.ZodLiteral<"oauth2">;
         authorizeUrl: z.ZodURL;
         tokenUrl: z.ZodURL;
+        clientId: z.ZodOptional<z.ZodString>;
         scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
         refresh: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
@@ -385,6 +387,7 @@ export declare const ManifestV1: z.ZodObject<{
             type: z.ZodLiteral<"oauth2">;
             authorizeUrl: z.ZodURL;
             tokenUrl: z.ZodURL;
+            clientId: z.ZodOptional<z.ZodString>;
             scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
             refresh: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{

package/dist/manifest.js

@@ -28,6 +28,8 @@ export const SyncAuth = z.discriminatedUnion('type', [
         type: z.literal('oauth2'),
         authorizeUrl: HttpsUrl,
         tokenUrl: HttpsUrl,
+        /** The developer's OAuth client id at their own service (public). The secret never goes in the manifest: it lives in the vault (APP_CLIENT_SECRET_REF). Added in 0.3.1. */
+        clientId: z.string().min(1).max(256).optional(),
         scopes: z.array(z.string().min(1)).default([]),
         refresh: z.boolean().default(true),
     }),

package/dist/registry.d.ts

@@ -74,6 +74,7 @@ export declare const AppVersionRecord: z.ZodObject<{
                 type: z.ZodLiteral<"oauth2">;
                 authorizeUrl: z.ZodURL;
                 tokenUrl: z.ZodURL;
+                clientId: z.ZodOptional<z.ZodString>;
                 scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
                 refresh: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>, z.ZodObject<{

package/dist/trust.d.ts

@@ -125,6 +125,29 @@ export declare const SecretRef: z.ZodObject<{
     name: z.ZodString;
 }, z.core.$strip>;
 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 declare const APP_CLIENT_INSTALL_ID: "ins_appclient";
+export declare const APP_CLIENT_SECRET_NAME: "oauth_client_secret";
+export declare function appClientSecretRef(appId: string, ownerWorkspaceId: string): SecretRef;
+/** Engine-side code exchange for an app connecting OUT (the handoff at api.thesoogroup.com/oauth/callback). Added in 0.3.1. */
+export declare const OAuthCodeExchange: z.ZodObject<{
+    install: z.ZodObject<{
+        workspaceId: z.ZodString;
+        installId: z.ZodString;
+        appId: z.ZodString;
+    }, z.core.$strip>;
+    ownerWorkspaceId: z.ZodString;
+    tokenUrl: z.ZodString;
+    clientId: z.ZodString;
+    code: z.ZodString;
+    codeVerifier: z.ZodOptional<z.ZodString>;
+    redirectUri: z.ZodString;
+}, z.core.$strip>;
+export type OAuthCodeExchange = z.infer<typeof OAuthCodeExchange>;
 /** What anyone outside the engine may see about a secret: never the value. */
 export declare const SecretInfo: z.ZodObject<{
     name: z.ZodString;
@@ -172,4 +195,12 @@ export interface EngineVaultRpc {
     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;
+    }>;
 }

package/dist/trust.js

@@ -92,6 +92,26 @@ export const SecretRef = z.object({
     appId: AppId,
     name: SecretName,
 });
+/**
+ * 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';
+export const APP_CLIENT_SECRET_NAME = 'oauth_client_secret';
+export function appClientSecretRef(appId, ownerWorkspaceId) {
+    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(),
+});
 /** What anyone outside the engine may see about a secret: never the value. */
 export const SecretInfo = z.object({
     name: SecretName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withloops.ai/contracts",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "The Loops developer platform contracts (zod): app manifest v1, scopes, events, the /v1 API envelope and registry records. Everything else builds on these.",
   "type": "module",
   "license": "UNLICENSED",

package/src/manifest.ts

@@ -36,6 +36,8 @@ export const SyncAuth = z.discriminatedUnion('type', [
     type: z.literal('oauth2'),
     authorizeUrl: HttpsUrl,
     tokenUrl: HttpsUrl,
+    /** The developer's OAuth client id at their own service (public). The secret never goes in the manifest: it lives in the vault (APP_CLIENT_SECRET_REF). Added in 0.3.1. */
+    clientId: z.string().min(1).max(256).optional(),
     scopes: z.array(z.string().min(1)).default([]),
     refresh: z.boolean().default(true),
   }),

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 }>;
 }