tapimo 0.14.0 → 0.15.1

package/dist/apps/management/routes/invitations.d.ts

@@ -1,4 +1,9 @@
 import * as z from 'zod/mini';
+import * as Db from '../../../db/Db.js';
+import * as Email from '../../../internal/Email.js';
+import * as Memberships from '../../../db/tables/memberships.js';
+import type * as Metrics from '../../../Metrics.js';
+import * as RateLimit from '../../../internal/RateLimit.js';
 import * as Response from '../../../internal/Response.js';
 import type { Environment } from '../App.js';
 /** Zod schemas owned by the invitations resource. */
@@ -130,15 +135,16 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
     "/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/invitations": {
         $post: {
             output: {
-                error: {
-                    code: "api_key_malformed";
-                    details?: readonly Response.error.Detail[] | undefined;
-                    message: string;
-                };
-                requestId: string;
+                createdAt: string;
+                email: string;
+                expiresAt: string;
+                id: string;
+                invitedBy: string;
+                orgId: string;
+                role: "admin" | "member" | "owner";
             };
             outputFormat: "json";
-            status: 400;
+            status: 200;
             input: {
                 param: {
                     orgId: string;
@@ -152,14 +158,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "api_key_invalid" | "api_key_missing";
+                    code: "api_key_malformed";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 401;
+            status: 400;
             input: {
                 param: {
                     orgId: string;
@@ -173,14 +179,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "api_key_forbidden" | "api_key_ip_forbidden";
+                    code: "body_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
+            status: 400;
             input: {
                 param: {
                     orgId: string;
@@ -194,14 +200,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "payment_required" | "rate_limit_exceeded";
+                    code: "param_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 429;
+            status: 400;
             input: {
                 param: {
                     orgId: string;
@@ -215,14 +221,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "upstream_error";
+                    code: "api_key_invalid" | "api_key_missing";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 502;
+            status: 401;
             input: {
                 param: {
                     orgId: string;
@@ -236,14 +242,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "organization_not_found";
+                    code: "api_key_forbidden" | "api_key_ip_forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 404;
+            status: 403;
             input: {
                 param: {
                     orgId: string;
@@ -278,14 +284,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "param_invalid";
+                    code: "organization_not_found";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 404;
             input: {
                 param: {
                     orgId: string;
@@ -299,14 +305,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "body_invalid";
+                    code: "payment_required" | "rate_limit_exceeded";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 429;
             input: {
                 param: {
                     orgId: string;
@@ -319,16 +325,15 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
             };
         } | {
             output: {
-                createdAt: string;
-                email: string;
-                expiresAt: string;
-                id: string;
-                invitedBy: string;
-                orgId: string;
-                role: "admin" | "member" | "owner";
+                error: {
+                    code: "upstream_error";
+                    details?: readonly Response.error.Detail[] | undefined;
+                    message: string;
+                };
+                requestId: string;
             };
             outputFormat: "json";
-            status: 200;
+            status: 502;
             input: {
                 param: {
                     orgId: string;
@@ -344,6 +349,25 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
 } & {
     "/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/invitations": {
         $get: {
+            output: {
+                data: {
+                    createdAt: string;
+                    email: string;
+                    expiresAt: string;
+                    id: string;
+                    invitedBy: string;
+                    orgId: string;
+                    role: "admin" | "member" | "owner";
+                }[];
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                param: {
+                    orgId: string;
+                };
+            };
+        } | {
             output: {
                 error: {
                     code: "api_key_malformed";
@@ -362,14 +386,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "api_key_invalid" | "api_key_missing";
+                    code: "param_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 401;
+            status: 400;
             input: {
                 param: {
                     orgId: string;
@@ -378,14 +402,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "api_key_forbidden" | "api_key_ip_forbidden";
+                    code: "api_key_invalid" | "api_key_missing";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
+            status: 401;
             input: {
                 param: {
                     orgId: string;
@@ -394,14 +418,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "payment_required" | "rate_limit_exceeded";
+                    code: "api_key_forbidden" | "api_key_ip_forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 429;
+            status: 403;
             input: {
                 param: {
                     orgId: string;
@@ -410,14 +434,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "upstream_error";
+                    code: "forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 502;
+            status: 403;
             input: {
                 param: {
                     orgId: string;
@@ -442,14 +466,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "forbidden";
+                    code: "payment_required" | "rate_limit_exceeded";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
+            status: 429;
             input: {
                 param: {
                     orgId: string;
@@ -458,43 +482,36 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "param_invalid";
+                    code: "upstream_error";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 502;
             input: {
                 param: {
                     orgId: string;
                 };
             };
-        } | {
+        };
+    };
+} & {
+    "/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/invitations/:invitationId{inv_[A-Za-z0-9_-]+}": {
+        $delete: {
             output: {
-                data: {
-                    createdAt: string;
-                    email: string;
-                    expiresAt: string;
-                    id: string;
-                    invitedBy: string;
-                    orgId: string;
-                    role: "admin" | "member" | "owner";
-                }[];
+                id: string;
             };
             outputFormat: "json";
             status: 200;
             input: {
                 param: {
+                    invitationId: string;
                     orgId: string;
                 };
             };
-        };
-    };
-} & {
-    "/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/invitations/:invitationId{inv_[A-Za-z0-9_-]+}": {
-        $delete: {
+        } | {
             output: {
                 error: {
                     code: "api_key_malformed";
@@ -514,14 +531,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "api_key_invalid" | "api_key_missing";
+                    code: "param_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 401;
+            status: 400;
             input: {
                 param: {
                     invitationId: string;
@@ -531,14 +548,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "api_key_forbidden" | "api_key_ip_forbidden";
+                    code: "api_key_invalid" | "api_key_missing";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
+            status: 401;
             input: {
                 param: {
                     invitationId: string;
@@ -548,14 +565,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "payment_required" | "rate_limit_exceeded";
+                    code: "api_key_forbidden" | "api_key_ip_forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 429;
+            status: 403;
             input: {
                 param: {
                     invitationId: string;
@@ -565,14 +582,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "upstream_error";
+                    code: "forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 502;
+            status: 403;
             input: {
                 param: {
                     invitationId: string;
@@ -599,14 +616,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "forbidden";
+                    code: "invitation_not_found";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
+            status: 404;
             input: {
                 param: {
                     invitationId: string;
@@ -616,14 +633,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "param_invalid";
+                    code: "payment_required" | "rate_limit_exceeded";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 429;
             input: {
                 param: {
                     invitationId: string;
@@ -633,26 +650,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "invitation_not_found";
+                    code: "upstream_error";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 404;
-            input: {
-                param: {
-                    invitationId: string;
-                    orgId: string;
-                };
-            };
-        } | {
-            output: {
-                id: string;
-            };
-            outputFormat: "json";
-            status: 200;
+            status: 502;
             input: {
                 param: {
                     invitationId: string;
@@ -664,6 +669,22 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
 } & {
     "/v1/invitations": {
         $get: {
+            output: {
+                data: {
+                    createdAt: string;
+                    email: string;
+                    expiresAt: string;
+                    id: string;
+                    invitedBy: string;
+                    orgId: string;
+                    role: "admin" | "member" | "owner";
+                    orgName: string;
+                }[];
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {};
+        } | {
             output: {
                 error: {
                     code: "api_key_malformed";
@@ -690,42 +711,26 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "upstream_error";
+                    code: "forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 502;
+            status: 403;
             input: {};
         } | {
             output: {
                 error: {
-                    code: "forbidden";
+                    code: "upstream_error";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
-            input: {};
-        } | {
-            output: {
-                data: {
-                    createdAt: string;
-                    email: string;
-                    expiresAt: string;
-                    id: string;
-                    invitedBy: string;
-                    orgId: string;
-                    role: "admin" | "member" | "owner";
-                    orgName: string;
-                }[];
-            };
-            outputFormat: "json";
-            status: 200;
+            status: 502;
             input: {};
         };
     };
@@ -733,15 +738,12 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
     "/v1/invitations/:invitationId{inv_[A-Za-z0-9_-]+}/accept": {
         $post: {
             output: {
-                error: {
-                    code: "api_key_malformed";
-                    details?: readonly Response.error.Detail[] | undefined;
-                    message: string;
-                };
-                requestId: string;
+                orgId: string;
+                role: "admin" | "member" | "owner";
+                userId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 200;
             input: {
                 param: {
                     invitationId: string;
@@ -750,14 +752,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "api_key_invalid" | "api_key_missing";
+                    code: "api_key_malformed";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 401;
+            status: 400;
             input: {
                 param: {
                     invitationId: string;
@@ -766,14 +768,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "upstream_error";
+                    code: "param_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 502;
+            status: 400;
             input: {
                 param: {
                     invitationId: string;
@@ -782,14 +784,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "forbidden";
+                    code: "api_key_invalid" | "api_key_missing";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
+            status: 401;
             input: {
                 param: {
                     invitationId: string;
@@ -798,14 +800,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "param_invalid";
+                    code: "forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 403;
             input: {
                 param: {
                     invitationId: string;
@@ -829,12 +831,15 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
             };
         } | {
             output: {
-                orgId: string;
-                role: "admin" | "member" | "owner";
-                userId: string;
+                error: {
+                    code: "upstream_error";
+                    details?: readonly Response.error.Detail[] | undefined;
+                    message: string;
+                };
+                requestId: string;
             };
             outputFormat: "json";
-            status: 200;
+            status: 502;
             input: {
                 param: {
                     invitationId: string;
@@ -846,15 +851,10 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
     "/v1/invitations/:invitationId{inv_[A-Za-z0-9_-]+}/decline": {
         $post: {
             output: {
-                error: {
-                    code: "api_key_malformed";
-                    details?: readonly Response.error.Detail[] | undefined;
-                    message: string;
-                };
-                requestId: string;
+                id: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 200;
             input: {
                 param: {
                     invitationId: string;
@@ -863,14 +863,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "api_key_invalid" | "api_key_missing";
+                    code: "api_key_malformed";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 401;
+            status: 400;
             input: {
                 param: {
                     invitationId: string;
@@ -879,14 +879,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "upstream_error";
+                    code: "param_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 502;
+            status: 400;
             input: {
                 param: {
                     invitationId: string;
@@ -895,14 +895,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "forbidden";
+                    code: "api_key_invalid" | "api_key_missing";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
+            status: 401;
             input: {
                 param: {
                     invitationId: string;
@@ -911,14 +911,14 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         } | {
             output: {
                 error: {
-                    code: "param_invalid";
+                    code: "forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 403;
             input: {
                 param: {
                     invitationId: string;
@@ -942,10 +942,15 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
             };
         } | {
             output: {
-                id: string;
+                error: {
+                    code: "upstream_error";
+                    details?: readonly Response.error.Detail[] | undefined;
+                    message: string;
+                };
+                requestId: string;
             };
             outputFormat: "json";
-            status: 200;
+            status: 502;
             input: {
                 param: {
                     invitationId: string;
@@ -954,4 +959,74 @@ export declare function invitations(): import("hono/hono-base").HonoBase<Environ
         };
     };
 }, "/", "/v1/invitations/:invitationId{inv_[A-Za-z0-9_-]+}/decline">;
+/** Consumes the shared quotas protecting invitation email dispatch. */
+export declare function consumeEmailRateLimit(options: consumeEmailRateLimit.Options): Promise<{
+    result: RateLimit.Result;
+    scope: string;
+} | undefined>;
+export declare namespace consumeEmailRateLimit {
+    /** Fields used to protect one invitation email dispatch. */
+    type Options = {
+        /** Stable identity for the initiating actor, when the caller has one. */
+        actor?: string | undefined;
+        /** Intended invitation recipient. */
+        email: string;
+        /** Whether this app has an email sender configured. */
+        enabled: boolean;
+        /** Bounded operational metrics sink for fail-open degradation. */
+        metrics?: Metrics.Metrics | undefined;
+        /** Shared counter store used by every invitation email entrypoint. */
+        rateLimit?: RateLimit.Store | undefined;
+    };
+}
+/** Records bounded invitation limiter degradation for operational alerting. */
+export declare function recordEmailRateLimitDegradation(options: recordEmailRateLimitDegradation.Options): void;
+export declare namespace recordEmailRateLimitDegradation {
+    /** Inputs for recording one invitation limiter degradation. */
+    type Options = {
+        /** Bounded operational metrics sink. */
+        metrics?: Metrics.Metrics | undefined;
+        /** Quota dimension whose counter degraded. */
+        scope: 'invitation-email-actor' | 'invitation-email-global' | 'invitation-email-recipient';
+    };
+}
+/** Creates an organization invitation and dispatches its email. */
+export declare function createInvitation(options: createInvitation.Options): Promise<{
+    acceptedAt: string | null;
+    createdAt: string;
+    email: string;
+    expiresAt: string;
+    grantsEarlyAccess: boolean;
+    id: string;
+    invitedBy: string;
+    orgId: string;
+    revokedAt: string | null;
+    role: "admin" | "member" | "owner";
+}>;
+export declare namespace createInvitation {
+    /** Fields required to create and deliver an invitation. */
+    type Options = {
+        /** Session user whose current organization role authorizes this write. */
+        callerUserId?: string | undefined;
+        /** Database receiving the pending invitation. */
+        db: Db.Db;
+        /** Invitee email. */
+        email: string;
+        /** Invitation expiry timestamp. */
+        expiresAt?: string | undefined;
+        /** Transactional email sender, when configured. */
+        invitationEmail?: Email.Sender | undefined;
+        /** Identity attributed with creating the invitation. */
+        invitedBy: string;
+        /** Organization receiving the invited member. */
+        org: {
+            id: string;
+            name: string;
+        };
+        /** Role granted after acceptance. */
+        role: Memberships.Role;
+        /** Keeps email delivery alive after the response. */
+        waitUntil?: ((promise: Promise<unknown>) => void) | undefined;
+    };
+}
 //# sourceMappingURL=invitations.d.ts.map