@geekapps/auth-nextjs 0.16.1 → 0.18.0

package/dist/connections.d.ts

@@ -1,22 +1,25 @@
+import { ClientOptions, Client } from 'openapi-fetch';
+
 /**
- * App Connections — chamar ações de negócio de OUTRA Application.
- *
- * 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.
+ * App Connections — agir como um usuário numa organização de OUTRA Application.
  *
- * 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ê
- * essa credencial — é esse o ponto do proxy.
+ * Uma conexão liga um USUÁRIO desta app (X) a uma organização da app alvo (Z)
+ * de que ele já é membro. Ele a aprova uma vez, no consent; o auth-server
+ * devolve a esta app um API token (`gka_…`). Daí em diante esta app guarda o
+ * token e o usa quando quiser — com ou sem o usuário logado, num cron, num
+ * workflow — trocando-o por um JWT curto que age COMO o usuário naquela
+ * organização (`getConnectionAccessToken`). As permissions são as do usuário
+ * na organização, hoje: mudou o role dele lá, a conexão muda junto; saiu da
+ * organização, ela para.
  *
- * O catálogo tipado (`GeekappsConnections`) vem do arquivo gerado por
- * `npx geekapps-connections`.
+ * ⚠️  ATENÇÃO — o API token é uma credencial de longa duração.
+ *   • Guarde-o cifrado, associado ao usuário que aprovou a conexão.
+ *   • Use-o só para agir em nome DESSE usuário. Usar o token de A para atender
+ *     um pedido de B dá a B o acesso de A à organização alvo.
+ *   • Restringir quem pode disparar uma chamada, e o que ela pode pedir, é
+ *     responsabilidade desta app: o auth-server não tem como saber.
+ *   • Vazou? Revogue no dashboard do Geekapps Auth ou gire com `rotateConnectionToken`.
  */
-/** 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). */
@@ -24,65 +27,23 @@ type AppConnectionsConfig = {
     clientSecret?: string;
 };
 /**
- * Preenchida por declaration merging no arquivo gerado
- * (`geekapps-connections.d.ts`). Vazia aqui de propósito: o SDK não sabe
- * quais apps existem — quem sabe é o auth-server, no momento da geração.
+ * Preenchida por declaration merging no `geekapps-connections/index.d.ts` que
+ * o SDK gera (em desenvolvimento) ou `npx geekapps-connections` escreve: uma
+ * chave por app conectável, com os `paths` do OpenAPI dela. Vazia aqui de
+ * propósito — quem sabe quais apps existem é o auth-server.
  */
 interface GeekappsConnections {
 }
-/** Erro de uma chamada de proxy — carrega o status HTTP para dar pra tratar. */
+/** Erro de uma chamada ao auth-server — carrega o status HTTP para dar pra tratar. */
 declare class AppConnectionError extends Error {
     readonly status: number;
     readonly code: string | undefined;
     readonly body: unknown;
     constructor(message: string, status: number, code: string | undefined, body: unknown);
 }
-/**
- * A chamada crua do proxy, para quando não há catálogo gerado. `targetAppId` é
- * o client_id da app alvo e `actionKey` é a AppAction.key — o mesmo valor que
- * aparece como scope no consent.
- */
-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>;
-type ConnectionRegistryEntry = {
-    appId: string;
-    actions: Record<string, string>;
-};
-/** Chamado por arquivos gerados no formato antigo. Não é necessário no fluxo automático. */
-declare function registerConnections(entries: Record<string, ConnectionRegistryEntry>): void;
-/**
- * Sem tipos gerados (primeira execução), qualquer `app.ação` é aceita. Assim
- * que o SDK escreve `geekapps-connections.d.ts`, a interface estendida passa a
- * valer e o TypeScript confere payload e retorno.
- */
-type AppConnectionsClient = keyof GeekappsConnections extends never ? Record<string, Record<string, (payload?: unknown, options?: ConnectionCallOptions) => Promise<unknown>>> : GeekappsConnections;
-/** Cliente com config explícita — para quem não usa as env vars padrão. */
-declare function createAppConnections(config?: AppConnectionsConfig): AppConnectionsClient;
-/** Catálogo explícito, como o gerado por `npx geekapps-connections` (`geekappsConnectionsCatalog`). */
-type ConnectionsCatalog = Record<string, {
-    readonly appId: string;
-    readonly actions: Readonly<Record<string, string>>;
-}>;
-/**
- * Opcional: usa um catálogo fixo em vez de consultar o auth-server. Útil em
- * testes ou quando a app não pode falar com o servidor em runtime.
- *
- *   const connections = defineAppConnections<GeekappsConnections>(geekappsConnectionsCatalog);
- */
-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). */
+    /** client_id da app ALVO (a que vai ser acessada). */
     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 "/"). */
@@ -93,13 +54,26 @@ type ConnectAppParams = {
 };
 /**
  * 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).
+ * httpOnly e redireciona para o consent, onde o usuário escolhe a organização
+ * e a validade. 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>;
+/** A conexão recém-criada. O `token` só aparece aqui, uma única vez. */
+type AppConnectionToken = {
+    /** API token (`gka_…`). Guarde-o cifrado, associado ao usuário que aprovou. */
+    token: string;
+    connectionId: string;
+    /** null = sem expiração. */
+    expiresAt: string | null;
+    /** Organização da app alvo em que a conexão age. */
+    organizationId: string;
+    targetAppId: string;
+};
 /**
  * Fecha o fluxo de `connectApp`. Chame no callback com o `code` e o `state`
- * da query; devolve o `returnTo` para você redirecionar. Lança
+ * da query; devolve o `returnTo` e a conexão, com o API token — a ÚNICA vez em
+ * que ele aparece, então persista-o antes de redirecionar. Lança
  * AppConnectionError se o state não bater ou o auth-server recusar.
  */
 declare function completeAppConnection(params: {
@@ -108,6 +82,86 @@ declare function completeAppConnection(params: {
     config?: AppConnectionsConfig;
 }): Promise<{
     returnTo: string;
+    connection: AppConnectionToken;
+}>;
+/** Resultado de `getConnectionAccessToken`. */
+type AppConnectionAccessToken = {
+    /** JWT curto: use em `Authorization: Bearer` contra a API da app alvo. */
+    accessToken: string;
+    /** Segundos até o JWT vencer. */
+    expiresIn: number;
+    organizationId: string;
+    targetAppId: string;
+    /** apiBaseUrl da app alvo, quando ela declarou uma. */
+    targetApiBaseUrl: string | null;
+    /** URL do OpenAPI da app alvo, quando ela declarou uma — fonte dos tipos. */
+    targetOpenApiUrl: string | null;
+};
+/**
+ * Troca o API token por um JWT curto que age como o usuário na organização da
+ * conexão. Não exige ninguém logado. O resultado fica em cache até perto de
+ * vencer, então pode ser chamado a cada requisição.
+ *
+ * Erros possíveis (`AppConnectionError.code`): `invalid_token`,
+ * `connection_inactive` (revogada), `connection_expired`,
+ * `membership_required` (o usuário saiu da organização).
+ */
+declare function getConnectionAccessToken(params: {
+    /** O API token guardado por esta app. */
+    connectionToken: string;
+    config?: AppConnectionsConfig;
+}): Promise<AppConnectionAccessToken>;
+/**
+ * Atalho: um `fetch` contra a API da app alvo já com o JWT da conexão. `path`
+ * é relativo ao `apiBaseUrl` da app alvo (ou uma URL absoluta).
+ */
+declare function connectionFetch(params: {
+    connectionToken: string;
+    path: string;
+    init?: RequestInit;
+    config?: AppConnectionsConfig;
+}): Promise<Response>;
+/**
+ * Cliente tipado para a API da app alvo, a partir do OpenAPI dela: o JWT da
+ * conexão é obtido, renovado e injetado a cada chamada.
+ *
+ * Os tipos de TODAS as apps conectáveis vêm de uma vez: em desenvolvimento o
+ * SDK baixa o OpenAPI de cada uma ao subir e escreve `geekapps-connections/`
+ * (ou rode `npx geekapps-connections`). Daí basta nomear a app:
+ *
+ *   const billing = await createConnectionClient({ app: "billing", connectionToken });
+ *   const { data } = await billing.GET("/charges", { params: { query: { limit: 10 } } });
+ *
+ * `app` só escolhe os tipos; a app alvo de verdade é a do token. Sem tipos
+ * gerados, passe os `paths` você mesmo: `createConnectionClient<paths>({ connectionToken })`.
+ *
+ * Requer o pacote `openapi-fetch` instalado na sua app.
+ */
+declare function createConnectionClient<App extends keyof GeekappsConnections>(params: ConnectionClientParams & {
+    app: App;
+}): Promise<Client<GeekappsConnections[App] & {}>>;
+declare function createConnectionClient<Paths extends {}>(params: ConnectionClientParams & {
+    app?: undefined;
+}): Promise<Client<Paths>>;
+type ConnectionClientParams = {
+    /** O API token guardado por esta app. */
+    connectionToken: string;
+    /** Sobrescreve o apiBaseUrl declarado pela app alvo. */
+    baseUrl?: string;
+    /** Demais opções do openapi-fetch (headers, querySerializer…). */
+    options?: Omit<ClientOptions, "baseUrl" | "fetch">;
+    config?: AppConnectionsConfig;
+};
+/**
+ * Gira o API token: o antigo deixa de valer na hora e o novo é devolvido (a
+ * validade da conexão não muda). Persista o novo no lugar do antigo.
+ */
+declare function rotateConnectionToken(params: {
+    connectionToken: string;
+    config?: AppConnectionsConfig;
+}): Promise<{
+    token: string;
+    expiresAt: string | null;
 }>;
 
-export { AppConnectionError, type AppConnectionsClient, type AppConnectionsConfig, type ConnectAppParams, type ConnectionCallOptions, type ConnectionsCatalog, type GeekappsConnections, appConnections, callAppConnection, completeAppConnection, connectApp, createAppConnections, defineAppConnections, registerConnections };
+export { type AppConnectionAccessToken, AppConnectionError, type AppConnectionToken, type AppConnectionsConfig, type ConnectAppParams, type GeekappsConnections, completeAppConnection, connectApp, connectionFetch, createConnectionClient, getConnectionAccessToken, rotateConnectionToken };