@geekapps/auth-nextjs 0.12.0 → 0.13.0

package/dist/connections.d.ts

@@ -1,11 +1,10 @@
 /**
  * App Connections — chamar ações de negócio de OUTRA Application.
  *
- * Uma conexão liga esta app (X) a uma app alvo (Y) e é aprovada UMA VEZ pelo
- * admin, que escolhe no consent as ações liberadas e a identidade dentro do Y
- * sob a qual elas rodam. Por isso a chamada aqui não leva usuário nenhum:
- * venha ela de um request com sessão, de um cron ou de um webhook, chega no Y
- * sempre com a mesma identidade e as mesmas permissões.
+ * Uma conexão liga um USUÁRIO desta app (X) a uma app alvo (Y). Ele a aprova
+ * uma vez no consent, escolhendo as ações liberadas e a organização dentro do
+ * Y sob a qual elas rodam. A chamada vai com o access token desse usuário (o
+ * da sessão, por padrão): é ele que diz ao proxy qual conexão usar.
  *
  * Nada aqui fala com a API do Y diretamente: tudo passa pelo proxy do
  * auth-server, que valida a conexão e injeta a credencial. Esta app nunca vê
@@ -14,6 +13,10 @@
  * O catálogo tipado (`GeekappsConnections`) vem do arquivo gerado por
  * `npx geekapps-connections`.
  */
+/** Opções por chamada. Sem `userToken`, usa o access token do usuário logado na sessão. */
+type ConnectionCallOptions = {
+    userToken?: string;
+};
 type AppConnectionsConfig = {
     issuer?: string;
     /** client_id/secret desta app (a consumidora, X). */
@@ -43,6 +46,8 @@ declare function callAppConnection<T = unknown>(params: {
     targetAppId: string;
     actionKey: string;
     payload?: unknown;
+    /** Access token do usuário dono da conexão. Padrão: o do usuário logado. */
+    userToken?: string;
     config?: AppConnectionsConfig;
 }): Promise<T>;
 /**
@@ -74,5 +79,36 @@ type ConnectionsCatalog = Record<string, ConnectionRegistryEntry | {
 declare function defineAppConnections<T>(catalog: ConnectionsCatalog, config?: AppConnectionsConfig): T;
 /** Cliente padrão, lendo GEEKAPPS_AUTH_CLIENT_ID / _SECRET do ambiente. */
 declare const appConnections: AppConnectionsClient;
+type ConnectAppParams = {
+    /** client_id da app ALVO (a que expõe as ações). */
+    targetAppId: string;
+    /** AppAction.key das ações pedidas — as mesmas que aparecem no consent. */
+    actions: string[];
+    /** URL desta app que recebe o retorno do consent (rota que chama `completeAppConnection`). Precisa estar nos redirect URIs desta app. */
+    redirectUri: string;
+    /** Para onde `completeAppConnection` manda o usuário depois (padrão "/"). */
+    returnTo?: string;
+    /** Nome desta app exibido no consent. */
+    displayName?: string;
+    config?: AppConnectionsConfig;
+};
+/**
+ * Inicia a conexão desta app com `targetAppId`: guarda PKCE/state em cookies
+ * httpOnly e redireciona para o consent. Chame de um Server Action ou Route
+ * Handler — não retorna (o `redirect` do Next interrompe a execução).
+ */
+declare function connectApp(params: ConnectAppParams): Promise<never>;
+/**
+ * Fecha o fluxo de `connectApp`. Chame no callback com o `code` e o `state`
+ * da query; devolve o `returnTo` para você redirecionar. Lança
+ * AppConnectionError se o state não bater ou o auth-server recusar.
+ */
+declare function completeAppConnection(params: {
+    code: string;
+    state: string;
+    config?: AppConnectionsConfig;
+}): Promise<{
+    returnTo: string;
+}>;
 
-export { AppConnectionError, type AppConnectionsClient, type AppConnectionsConfig, type ConnectionsCatalog, type GeekappsConnections, appConnections, callAppConnection, createAppConnections, defineAppConnections, registerConnections };
+export { AppConnectionError, type AppConnectionsClient, type AppConnectionsConfig, type ConnectAppParams, type ConnectionCallOptions, type ConnectionsCatalog, type GeekappsConnections, appConnections, callAppConnection, completeAppConnection, connectApp, createAppConnections, defineAppConnections, registerConnections };