tychat-contracts 1.3.2 → 1.3.4

package/dist/ai/ai-integration-response.dto.d.ts

@@ -4,5 +4,8 @@ export declare class AiIntegrationResponseDto {
     response: AiStructuredResponseDto;
     output?: string;
     aiUsageId?: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
 }
 //# sourceMappingURL=ai-integration-response.dto.d.ts.map

package/dist/ai/ai-integration-response.dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-integration-response.dto.d.ts","sourceRoot":"","sources":["../../src/ai/ai-integration-response.dto.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,qBAAa,wBAAwB;IAOnC,MAAM,EAAE,MAAM,CAAC;IAQf,QAAQ,EAAE,uBAAuB,CAAC;IAUlC,MAAM,CAAC,EAAE,MAAM,CAAC;IAQhB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"ai-integration-response.dto.d.ts","sourceRoot":"","sources":["../../src/ai/ai-integration-response.dto.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,qBAAa,wBAAwB;IAOnC,MAAM,EAAE,MAAM,CAAC;IAQf,QAAQ,EAAE,uBAAuB,CAAC;IAUlC,MAAM,CAAC,EAAE,MAAM,CAAC;IAQhB,SAAS,CAAC,EAAE,MAAM,CAAC;IAOnB,YAAY,CAAC,EAAE,MAAM,CAAC;IAOtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAO1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/ai/ai-integration-response.dto.js

@@ -19,6 +19,9 @@ class AiIntegrationResponseDto {
     response;
     output;
     aiUsageId;
+    promptTokens;
+    completionTokens;
+    totalTokens;
 }
 exports.AiIntegrationResponseDto = AiIntegrationResponseDto;
 __decorate([
@@ -59,3 +62,27 @@ __decorate([
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
 ], AiIntegrationResponseDto.prototype, "aiUsageId", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Prompt tokens consumed in this AI request',
+        example: 120,
+    }),
+    (0, class_validator_1.IsOptional)(),
+    __metadata("design:type", Number)
+], AiIntegrationResponseDto.prototype, "promptTokens", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Completion tokens generated in this AI request',
+        example: 90,
+    }),
+    (0, class_validator_1.IsOptional)(),
+    __metadata("design:type", Number)
+], AiIntegrationResponseDto.prototype, "completionTokens", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Total tokens consumed in this AI request',
+        example: 210,
+    }),
+    (0, class_validator_1.IsOptional)(),
+    __metadata("design:type", Number)
+], AiIntegrationResponseDto.prototype, "totalTokens", void 0);

package/dist/analytics/analytics-emitter.helper.d.ts

@@ -14,7 +14,7 @@ export interface EmitAnalyticEventOptions {
 /**
  * Builds the Kafka payload to be sent to the analytics service.
  *
- * Usage (fire-and-forget via ClientKafka.emit):
+ * Usage (fire-and-forget via ClientProxy.emit):
  * ```ts
  * this.analyticsClient.emit(
  *   TOPIC_ANALYTICS_EVENT,

package/dist/analytics/analytics-emitter.helper.js

@@ -8,7 +8,7 @@ Object.defineProperty(exports, "TOPIC_ANALYTICS_EVENT", { enumerable: true, get:
 /**
  * Builds the Kafka payload to be sent to the analytics service.
  *
- * Usage (fire-and-forget via ClientKafka.emit):
+ * Usage (fire-and-forget via ClientProxy.emit):
  * ```ts
  * this.analyticsClient.emit(
  *   TOPIC_ANALYTICS_EVENT,

package/dist/configurations/ai-tool-policy.dto.d.ts

@@ -0,0 +1,26 @@
+import { type AiToolFallbackMode, type AiToolKey, type AiToolPolicyLevel } from './ai-tool-policy.enums';
+export declare class AiToolPolicyDto {
+    toolKey: AiToolKey;
+    enabled: boolean;
+    fallbackMode?: AiToolFallbackMode;
+    level?: AiToolPolicyLevel;
+}
+export declare class UpdateAiToolPolicyDto {
+    toolKey: AiToolKey;
+    enabled: boolean;
+    fallbackMode?: AiToolFallbackMode;
+}
+export declare class UpdateAiToolPoliciesDto {
+    policies: UpdateAiToolPolicyDto[];
+}
+export declare class ResolveAiToolPoliciesQueryDto {
+    tenantId: string;
+    unitId?: number;
+}
+export declare class EffectiveAiToolPolicyDto extends AiToolPolicyDto {
+    reasonCode?: string;
+}
+export declare class EffectiveAiToolPoliciesDto {
+    policies: EffectiveAiToolPolicyDto[];
+}
+//# sourceMappingURL=ai-tool-policy.dto.d.ts.map

package/dist/configurations/ai-tool-policy.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-tool-policy.dto.d.ts","sourceRoot":"","sources":["../../src/configurations/ai-tool-policy.dto.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAEhC,qBAAa,eAAe;IAG1B,OAAO,EAAE,SAAS,CAAC;IAInB,OAAO,EAAE,OAAO,CAAC;IAKjB,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAKlC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,qBAAa,qBAAqB;IAGhC,OAAO,EAAE,SAAS,CAAC;IAInB,OAAO,EAAE,OAAO,CAAC;IAKjB,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED,qBAAa,uBAAuB;IAKlC,QAAQ,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAED,qBAAa,6BAA6B;IAIxC,QAAQ,EAAE,MAAM,CAAC;IAMjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,wBAAyB,SAAQ,eAAe;IAI3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,0BAA0B;IAKrC,QAAQ,EAAE,wBAAwB,EAAE,CAAC;CACtC"}

package/dist/configurations/ai-tool-policy.dto.js

@@ -0,0 +1,117 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EffectiveAiToolPoliciesDto = exports.EffectiveAiToolPolicyDto = exports.ResolveAiToolPoliciesQueryDto = exports.UpdateAiToolPoliciesDto = exports.UpdateAiToolPolicyDto = exports.AiToolPolicyDto = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const ai_tool_policy_enums_1 = require("./ai-tool-policy.enums");
+class AiToolPolicyDto {
+    toolKey;
+    enabled;
+    fallbackMode;
+    level;
+}
+exports.AiToolPolicyDto = AiToolPolicyDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ enum: ai_tool_policy_enums_1.AI_TOOL_KEYS }),
+    (0, class_validator_1.IsEnum)(ai_tool_policy_enums_1.AI_TOOL_KEYS),
+    __metadata("design:type", String)
+], AiToolPolicyDto.prototype, "toolKey", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], AiToolPolicyDto.prototype, "enabled", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ enum: ai_tool_policy_enums_1.AI_TOOL_FALLBACK_MODES }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(ai_tool_policy_enums_1.AI_TOOL_FALLBACK_MODES),
+    __metadata("design:type", String)
+], AiToolPolicyDto.prototype, "fallbackMode", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ enum: ai_tool_policy_enums_1.AI_TOOL_POLICY_LEVELS }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(ai_tool_policy_enums_1.AI_TOOL_POLICY_LEVELS),
+    __metadata("design:type", String)
+], AiToolPolicyDto.prototype, "level", void 0);
+class UpdateAiToolPolicyDto {
+    toolKey;
+    enabled;
+    fallbackMode;
+}
+exports.UpdateAiToolPolicyDto = UpdateAiToolPolicyDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ enum: ai_tool_policy_enums_1.AI_TOOL_KEYS }),
+    (0, class_validator_1.IsEnum)(ai_tool_policy_enums_1.AI_TOOL_KEYS),
+    __metadata("design:type", String)
+], UpdateAiToolPolicyDto.prototype, "toolKey", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], UpdateAiToolPolicyDto.prototype, "enabled", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ enum: ai_tool_policy_enums_1.AI_TOOL_FALLBACK_MODES }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(ai_tool_policy_enums_1.AI_TOOL_FALLBACK_MODES),
+    __metadata("design:type", String)
+], UpdateAiToolPolicyDto.prototype, "fallbackMode", void 0);
+class UpdateAiToolPoliciesDto {
+    policies;
+}
+exports.UpdateAiToolPoliciesDto = UpdateAiToolPoliciesDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ type: () => [UpdateAiToolPolicyDto] }),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => UpdateAiToolPolicyDto),
+    __metadata("design:type", Array)
+], UpdateAiToolPoliciesDto.prototype, "policies", void 0);
+class ResolveAiToolPoliciesQueryDto {
+    tenantId;
+    unitId;
+}
+exports.ResolveAiToolPoliciesQueryDto = ResolveAiToolPoliciesQueryDto;
+__decorate([
+    (0, swagger_1.ApiProperty)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], ResolveAiToolPoliciesQueryDto.prototype, "tenantId", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ minimum: 1 }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], ResolveAiToolPoliciesQueryDto.prototype, "unitId", void 0);
+class EffectiveAiToolPolicyDto extends AiToolPolicyDto {
+    reasonCode;
+}
+exports.EffectiveAiToolPolicyDto = EffectiveAiToolPolicyDto;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], EffectiveAiToolPolicyDto.prototype, "reasonCode", void 0);
+class EffectiveAiToolPoliciesDto {
+    policies;
+}
+exports.EffectiveAiToolPoliciesDto = EffectiveAiToolPoliciesDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ type: () => [EffectiveAiToolPolicyDto] }),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => EffectiveAiToolPolicyDto),
+    __metadata("design:type", Array)
+], EffectiveAiToolPoliciesDto.prototype, "policies", void 0);

package/dist/configurations/ai-tool-policy.enums.d.ts

@@ -0,0 +1,7 @@
+export declare const AI_TOOL_KEYS: readonly ["get_procedures_clinic", "get_clinic_opening_hours", "get_available_slots", "search_health_professionals", "update_patient", "search_patients_by_phone", "create_patient", "create_appointment", "add_appointment_procedures", "list_patient_appointments", "cancel_appointment", "submit_satisfaction"];
+export type AiToolKey = (typeof AI_TOOL_KEYS)[number];
+export declare const AI_TOOL_POLICY_LEVELS: readonly ["global", "plan", "tenant", "unit"];
+export type AiToolPolicyLevel = (typeof AI_TOOL_POLICY_LEVELS)[number];
+export declare const AI_TOOL_FALLBACK_MODES: readonly ["transfer_to_human", "unavailable_message"];
+export type AiToolFallbackMode = (typeof AI_TOOL_FALLBACK_MODES)[number];
+//# sourceMappingURL=ai-tool-policy.enums.d.ts.map

package/dist/configurations/ai-tool-policy.enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-tool-policy.enums.d.ts","sourceRoot":"","sources":["../../src/configurations/ai-tool-policy.enums.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,oTAaf,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,eAAO,MAAM,qBAAqB,+CAAgD,CAAC;AACnF,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,eAAO,MAAM,sBAAsB,uDAGzB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/configurations/ai-tool-policy.enums.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AI_TOOL_FALLBACK_MODES = exports.AI_TOOL_POLICY_LEVELS = exports.AI_TOOL_KEYS = void 0;
+exports.AI_TOOL_KEYS = [
+    'get_procedures_clinic',
+    'get_clinic_opening_hours',
+    'get_available_slots',
+    'search_health_professionals',
+    'update_patient',
+    'search_patients_by_phone',
+    'create_patient',
+    'create_appointment',
+    'add_appointment_procedures',
+    'list_patient_appointments',
+    'cancel_appointment',
+    'submit_satisfaction',
+];
+exports.AI_TOOL_POLICY_LEVELS = ['global', 'plan', 'tenant', 'unit'];
+exports.AI_TOOL_FALLBACK_MODES = [
+    'transfer_to_human',
+    'unavailable_message',
+];

package/dist/configurations/index.d.ts

@@ -1,6 +1,8 @@
 export * from './opening-hours-slot.dto';
 export * from './update-clinic-configuration.dto';
 export * from './clinic-configuration.dto';
+export * from './ai-tool-policy.enums';
+export * from './ai-tool-policy.dto';
 export * from './plan-summary.dto';
 export * from './tenant-limits-summary.dto';
 export * from './configuration-tenant-summary.dto';

package/dist/configurations/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/configurations/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/configurations/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC"}

package/dist/configurations/index.js

@@ -17,6 +17,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./opening-hours-slot.dto"), exports);
 __exportStar(require("./update-clinic-configuration.dto"), exports);
 __exportStar(require("./clinic-configuration.dto"), exports);
+__exportStar(require("./ai-tool-policy.enums"), exports);
+__exportStar(require("./ai-tool-policy.dto"), exports);
 __exportStar(require("./plan-summary.dto"), exports);
 __exportStar(require("./tenant-limits-summary.dto"), exports);
 __exportStar(require("./configuration-tenant-summary.dto"), exports);

package/dist/configurations/plan-summary.dto.d.ts

@@ -14,6 +14,7 @@ export declare class PlanSummaryDto {
     maxAttendants: number;
     maxAdministrators: number;
     maxProcedures: number;
+    monthlyAiTokens: number;
     createdAt?: Date;
     updatedAt?: Date;
 }

package/dist/configurations/plan-summary.dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-summary.dto.d.ts","sourceRoot":"","sources":["../../src/configurations/plan-summary.dto.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,qBAAa,cAAc;IAEzB,EAAE,EAAE,MAAM,CAAC;IAGX,IAAI,EAAE,MAAM,CAAC;IAGb,KAAK,EAAE,MAAM,CAAC;IAGd,cAAc,EAAE,MAAM,CAAC;IAGvB,QAAQ,EAAE,MAAM,CAAC;IAGjB,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IAG9B,oBAAoB,EAAE,MAAM,CAAC;IAG7B,WAAW,EAAE,MAAM,CAAC;IAGpB,UAAU,EAAE,MAAM,CAAC;IAGnB,aAAa,EAAE,MAAM,CAAC;IAGtB,iBAAiB,EAAE,MAAM,CAAC;IAG1B,aAAa,EAAE,MAAM,CAAC;IAGtB,SAAS,CAAC,EAAE,IAAI,CAAC;IAGjB,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB"}
+{"version":3,"file":"plan-summary.dto.d.ts","sourceRoot":"","sources":["../../src/configurations/plan-summary.dto.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,qBAAa,cAAc;IAEzB,EAAE,EAAE,MAAM,CAAC;IAGX,IAAI,EAAE,MAAM,CAAC;IAGb,KAAK,EAAE,MAAM,CAAC;IAGd,cAAc,EAAE,MAAM,CAAC;IAGvB,QAAQ,EAAE,MAAM,CAAC;IAGjB,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IAG9B,oBAAoB,EAAE,MAAM,CAAC;IAG7B,WAAW,EAAE,MAAM,CAAC;IAGpB,UAAU,EAAE,MAAM,CAAC;IAGnB,aAAa,EAAE,MAAM,CAAC;IAGtB,iBAAiB,EAAE,MAAM,CAAC;IAG1B,aAAa,EAAE,MAAM,CAAC;IAGtB,eAAe,EAAE,MAAM,CAAC;IAGxB,SAAS,CAAC,EAAE,IAAI,CAAC;IAGjB,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB"}

package/dist/configurations/plan-summary.dto.js

@@ -27,6 +27,7 @@ class PlanSummaryDto {
     maxAttendants;
     maxAdministrators;
     maxProcedures;
+    monthlyAiTokens;
     createdAt;
     updatedAt;
 }
@@ -79,6 +80,10 @@ __decorate([
     (0, swagger_1.ApiProperty)({ description: 'Max procedures', example: 200 }),
     __metadata("design:type", Number)
 ], PlanSummaryDto.prototype, "maxProcedures", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Monthly AI token allowance', example: 5000 }),
+    __metadata("design:type", Number)
+], PlanSummaryDto.prototype, "monthlyAiTokens", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)(),
     __metadata("design:type", Date)

package/dist/tenants/consume-tenant-ai-tokens.dto.d.ts

@@ -0,0 +1,14 @@
+import { TenantAiTokenStateDto } from './tenant-ai-token-state.dto';
+export declare const TENANT_AI_TOKEN_CONSUMPTION_SOURCES: readonly ["ai.request", "ai.followup.generate"];
+export type TenantAiTokenConsumptionSourceDto = (typeof TENANT_AI_TOKEN_CONSUMPTION_SOURCES)[number];
+export declare class ConsumeTenantAiTokensDto {
+    tenant: string;
+    tokens: number;
+    source: TenantAiTokenConsumptionSourceDto;
+    correlationId?: string;
+}
+export declare class ConsumeTenantAiTokensResponseDto extends TenantAiTokenStateDto {
+    consumed: number;
+    becameZero: boolean;
+}
+//# sourceMappingURL=consume-tenant-ai-tokens.dto.d.ts.map

package/dist/tenants/consume-tenant-ai-tokens.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consume-tenant-ai-tokens.dto.d.ts","sourceRoot":"","sources":["../../src/tenants/consume-tenant-ai-tokens.dto.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,eAAO,MAAM,mCAAmC,iDAAkD,CAAC;AACnG,MAAM,MAAM,iCAAiC,GAC3C,CAAC,OAAO,mCAAmC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,qBAAa,wBAAwB;IAInC,MAAM,EAAE,MAAM,CAAC;IAKf,MAAM,EAAE,MAAM,CAAC;IAOf,MAAM,EAAE,iCAAiC,CAAC;IAK1C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,gCAAiC,SAAQ,qBAAqB;IAIzE,QAAQ,EAAE,MAAM,CAAC;IAGjB,UAAU,EAAE,OAAO,CAAC;CACrB"}

package/dist/tenants/consume-tenant-ai-tokens.dto.js

@@ -0,0 +1,64 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsumeTenantAiTokensResponseDto = exports.ConsumeTenantAiTokensDto = exports.TENANT_AI_TOKEN_CONSUMPTION_SOURCES = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+const tenant_ai_token_state_dto_1 = require("./tenant-ai-token-state.dto");
+exports.TENANT_AI_TOKEN_CONSUMPTION_SOURCES = ['ai.request', 'ai.followup.generate'];
+class ConsumeTenantAiTokensDto {
+    tenant;
+    tokens;
+    source;
+    correlationId;
+}
+exports.ConsumeTenantAiTokensDto = ConsumeTenantAiTokensDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Tenant slug', example: 'clinic-alpha' }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], ConsumeTenantAiTokensDto.prototype, "tenant", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Tokens to consume', example: 420 }),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], ConsumeTenantAiTokensDto.prototype, "tokens", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Deterministic source of consumption',
+        enum: exports.TENANT_AI_TOKEN_CONSUMPTION_SOURCES,
+    }),
+    (0, class_validator_1.IsIn)(exports.TENANT_AI_TOKEN_CONSUMPTION_SOURCES),
+    __metadata("design:type", String)
+], ConsumeTenantAiTokensDto.prototype, "source", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Optional operation correlation id', required: false }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], ConsumeTenantAiTokensDto.prototype, "correlationId", void 0);
+class ConsumeTenantAiTokensResponseDto extends tenant_ai_token_state_dto_1.TenantAiTokenStateDto {
+    consumed;
+    becameZero;
+}
+exports.ConsumeTenantAiTokensResponseDto = ConsumeTenantAiTokensResponseDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'How many tokens were actually consumed', example: 420 }),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], ConsumeTenantAiTokensResponseDto.prototype, "consumed", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'True when the balance reached zero in this operation', example: false }),
+    __metadata("design:type", Boolean)
+], ConsumeTenantAiTokensResponseDto.prototype, "becameZero", void 0);

package/dist/tenants/index.d.ts

@@ -3,4 +3,8 @@ export * from './get-tenant-by-address.query.dto';
 export * from './tenant-public-by-address-response.dto';
 export * from './whatsapp-provider-kind.dto';
 export * from './tenant-slug.util';
+export * from './tenant-ai-token-state.dto';
+export * from './consume-tenant-ai-tokens.dto';
+export * from './recharge-tenant-ai-tokens.dto';
+export * from './renew-tenant-ai-tokens.dto';
 //# sourceMappingURL=index.d.ts.map

package/dist/tenants/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tenants/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tenants/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC"}

package/dist/tenants/index.js

@@ -19,3 +19,7 @@ __exportStar(require("./get-tenant-by-address.query.dto"), exports);
 __exportStar(require("./tenant-public-by-address-response.dto"), exports);
 __exportStar(require("./whatsapp-provider-kind.dto"), exports);
 __exportStar(require("./tenant-slug.util"), exports);
+__exportStar(require("./tenant-ai-token-state.dto"), exports);
+__exportStar(require("./consume-tenant-ai-tokens.dto"), exports);
+__exportStar(require("./recharge-tenant-ai-tokens.dto"), exports);
+__exportStar(require("./renew-tenant-ai-tokens.dto"), exports);

package/dist/tenants/recharge-tenant-ai-tokens.dto.d.ts

@@ -0,0 +1,10 @@
+import { TenantAiTokenStateDto } from './tenant-ai-token-state.dto';
+export declare class RechargeTenantAiTokensDto {
+    tenantId: string;
+    amount: number;
+    reason?: string;
+}
+export declare class RechargeTenantAiTokensResponseDto extends TenantAiTokenStateDto {
+    added: number;
+}
+//# sourceMappingURL=recharge-tenant-ai-tokens.dto.d.ts.map

package/dist/tenants/recharge-tenant-ai-tokens.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recharge-tenant-ai-tokens.dto.d.ts","sourceRoot":"","sources":["../../src/tenants/recharge-tenant-ai-tokens.dto.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,qBAAa,yBAAyB;IAIpC,QAAQ,EAAE,MAAM,CAAC;IAKjB,MAAM,EAAE,MAAM,CAAC;IAKf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,iCAAkC,SAAQ,qBAAqB;IAI1E,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/tenants/recharge-tenant-ai-tokens.dto.js

@@ -0,0 +1,49 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RechargeTenantAiTokensResponseDto = exports.RechargeTenantAiTokensDto = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+const tenant_ai_token_state_dto_1 = require("./tenant-ai-token-state.dto");
+class RechargeTenantAiTokensDto {
+    tenantId;
+    amount;
+    reason;
+}
+exports.RechargeTenantAiTokensDto = RechargeTenantAiTokensDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Tenant id (UUID)', example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RechargeTenantAiTokensDto.prototype, "tenantId", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Amount of tokens to add', example: 10000 }),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], RechargeTenantAiTokensDto.prototype, "amount", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ description: 'Free text reason for audit', example: 'Recarga manual realizada pelo financeiro' }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RechargeTenantAiTokensDto.prototype, "reason", void 0);
+class RechargeTenantAiTokensResponseDto extends tenant_ai_token_state_dto_1.TenantAiTokenStateDto {
+    added;
+}
+exports.RechargeTenantAiTokensResponseDto = RechargeTenantAiTokensResponseDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Recharge amount applied', example: 10000 }),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], RechargeTenantAiTokensResponseDto.prototype, "added", void 0);

package/dist/tenants/renew-tenant-ai-tokens.dto.d.ts

@@ -0,0 +1,7 @@
+export declare class RenewTenantAiTokensDto {
+    tenantId?: string;
+}
+export declare class RenewTenantAiTokensResponseDto {
+    renewedCount: number;
+}
+//# sourceMappingURL=renew-tenant-ai-tokens.dto.d.ts.map

package/dist/tenants/renew-tenant-ai-tokens.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renew-tenant-ai-tokens.dto.d.ts","sourceRoot":"","sources":["../../src/tenants/renew-tenant-ai-tokens.dto.ts"],"names":[],"mappings":"AAGA,qBAAa,sBAAsB;IAIjC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,8BAA8B;IAIzC,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/tenants/renew-tenant-ai-tokens.dto.js

@@ -0,0 +1,34 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RenewTenantAiTokensResponseDto = exports.RenewTenantAiTokensDto = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+class RenewTenantAiTokensDto {
+    tenantId;
+}
+exports.RenewTenantAiTokensDto = RenewTenantAiTokensDto;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ description: 'Optional tenant id to renew one tenant only' }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RenewTenantAiTokensDto.prototype, "tenantId", void 0);
+class RenewTenantAiTokensResponseDto {
+    renewedCount;
+}
+exports.RenewTenantAiTokensResponseDto = RenewTenantAiTokensResponseDto;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({ description: 'How many tenants were renewed', example: 12 }),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], RenewTenantAiTokensResponseDto.prototype, "renewedCount", void 0);

package/dist/tenants/tenant-ai-token-state.dto.d.ts

@@ -0,0 +1,13 @@
+export declare class TenantAiTokenStateDto {
+    tenant: string;
+    currentBalance: number;
+    monthlyAllowance: number;
+    blocked: boolean;
+    cycleStartedAt: string;
+    nextRenewalAt: string;
+    recurrenceDays: number;
+    canUseAi: boolean;
+    lastConsumedAt?: string;
+    lastRechargedAt?: string;
+}
+//# sourceMappingURL=tenant-ai-token-state.dto.d.ts.map

package/dist/tenants/tenant-ai-token-state.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-ai-token-state.dto.d.ts","sourceRoot":"","sources":["../../src/tenants/tenant-ai-token-state.dto.ts"],"names":[],"mappings":"AAGA,qBAAa,qBAAqB;IAIhC,MAAM,EAAE,MAAM,CAAC;IAKf,cAAc,EAAE,MAAM,CAAC;IAKvB,gBAAgB,EAAE,MAAM,CAAC;IAIzB,OAAO,EAAE,OAAO,CAAC;IAIjB,cAAc,EAAE,MAAM,CAAC;IAIvB,aAAa,EAAE,MAAM,CAAC;IAKtB,cAAc,EAAE,MAAM,CAAC;IAIvB,QAAQ,EAAE,OAAO,CAAC;IAKlB,cAAc,CAAC,EAAE,MAAM,CAAC;IAKxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B"}

package/dist/tenants/tenant-ai-token-state.dto.js

@@ -0,0 +1,83 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TenantAiTokenStateDto = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+class TenantAiTokenStateDto {
+    tenant;
+    currentBalance;
+    monthlyAllowance;
+    blocked;
+    cycleStartedAt;
+    nextRenewalAt;
+    recurrenceDays;
+    canUseAi;
+    lastConsumedAt;
+    lastRechargedAt;
+}
+exports.TenantAiTokenStateDto = TenantAiTokenStateDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Tenant slug', example: 'clinic-alpha' }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], TenantAiTokenStateDto.prototype, "tenant", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Current remaining AI tokens', example: 2400 }),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], TenantAiTokenStateDto.prototype, "currentBalance", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Monthly allowance configured for current cycle', example: 5000 }),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], TenantAiTokenStateDto.prototype, "monthlyAllowance", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Whether IA is blocked for this tenant', example: false }),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], TenantAiTokenStateDto.prototype, "blocked", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Current cycle start timestamp', example: '2026-04-01T00:00:00.000Z' }),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], TenantAiTokenStateDto.prototype, "cycleStartedAt", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Next monthly renewal timestamp', example: '2026-05-01T00:00:00.000Z' }),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], TenantAiTokenStateDto.prototype, "nextRenewalAt", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Plan recurrence in days used for renewal', example: 30 }),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], TenantAiTokenStateDto.prototype, "recurrenceDays", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'True when balance is currently greater than zero', example: true }),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], TenantAiTokenStateDto.prototype, "canUseAi", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Last consumption timestamp', required: false }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], TenantAiTokenStateDto.prototype, "lastConsumedAt", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({ description: 'Last recharge timestamp', required: false }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], TenantAiTokenStateDto.prototype, "lastRechargedAt", void 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tychat-contracts",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "DTOs compartilhados com class-validator (API e microserviços)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/ai/ai-integration-response.dto.ts

@@ -37,4 +37,25 @@ export class AiIntegrationResponseDto {
   @IsOptional()
   @IsString()
   aiUsageId?: string;
+
+  @ApiPropertyOptional({
+    description: 'Prompt tokens consumed in this AI request',
+    example: 120,
+  })
+  @IsOptional()
+  promptTokens?: number;
+
+  @ApiPropertyOptional({
+    description: 'Completion tokens generated in this AI request',
+    example: 90,
+  })
+  @IsOptional()
+  completionTokens?: number;
+
+  @ApiPropertyOptional({
+    description: 'Total tokens consumed in this AI request',
+    example: 210,
+  })
+  @IsOptional()
+  totalTokens?: number;
 }

package/src/analytics/analytics-emitter.helper.ts

@@ -17,7 +17,7 @@ export interface EmitAnalyticEventOptions {
 /**
  * Builds the Kafka payload to be sent to the analytics service.
  *
- * Usage (fire-and-forget via ClientKafka.emit):
+ * Usage (fire-and-forget via ClientProxy.emit):
  * ```ts
  * this.analyticsClient.emit(
  *   TOPIC_ANALYTICS_EVENT,

package/src/configurations/ai-tool-policy.dto.ts

@@ -0,0 +1,92 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  IsArray,
+  IsBoolean,
+  IsEnum,
+  IsInt,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  Min,
+  ValidateNested,
+} from 'class-validator';
+import {
+  AI_TOOL_FALLBACK_MODES,
+  AI_TOOL_KEYS,
+  AI_TOOL_POLICY_LEVELS,
+  type AiToolFallbackMode,
+  type AiToolKey,
+  type AiToolPolicyLevel,
+} from './ai-tool-policy.enums';
+
+export class AiToolPolicyDto {
+  @ApiProperty({ enum: AI_TOOL_KEYS })
+  @IsEnum(AI_TOOL_KEYS)
+  toolKey: AiToolKey;
+
+  @ApiProperty()
+  @IsBoolean()
+  enabled: boolean;
+
+  @ApiPropertyOptional({ enum: AI_TOOL_FALLBACK_MODES })
+  @IsOptional()
+  @IsEnum(AI_TOOL_FALLBACK_MODES)
+  fallbackMode?: AiToolFallbackMode;
+
+  @ApiPropertyOptional({ enum: AI_TOOL_POLICY_LEVELS })
+  @IsOptional()
+  @IsEnum(AI_TOOL_POLICY_LEVELS)
+  level?: AiToolPolicyLevel;
+}
+
+export class UpdateAiToolPolicyDto {
+  @ApiProperty({ enum: AI_TOOL_KEYS })
+  @IsEnum(AI_TOOL_KEYS)
+  toolKey: AiToolKey;
+
+  @ApiProperty()
+  @IsBoolean()
+  enabled: boolean;
+
+  @ApiPropertyOptional({ enum: AI_TOOL_FALLBACK_MODES })
+  @IsOptional()
+  @IsEnum(AI_TOOL_FALLBACK_MODES)
+  fallbackMode?: AiToolFallbackMode;
+}
+
+export class UpdateAiToolPoliciesDto {
+  @ApiProperty({ type: () => [UpdateAiToolPolicyDto] })
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => UpdateAiToolPolicyDto)
+  policies: UpdateAiToolPolicyDto[];
+}
+
+export class ResolveAiToolPoliciesQueryDto {
+  @ApiProperty()
+  @IsString()
+  @IsNotEmpty()
+  tenantId: string;
+
+  @ApiPropertyOptional({ minimum: 1 })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  unitId?: number;
+}
+
+export class EffectiveAiToolPolicyDto extends AiToolPolicyDto {
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  reasonCode?: string;
+}
+
+export class EffectiveAiToolPoliciesDto {
+  @ApiProperty({ type: () => [EffectiveAiToolPolicyDto] })
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => EffectiveAiToolPolicyDto)
+  policies: EffectiveAiToolPolicyDto[];
+}

package/src/configurations/ai-tool-policy.enums.ts

@@ -0,0 +1,25 @@
+export const AI_TOOL_KEYS = [
+  'get_procedures_clinic',
+  'get_clinic_opening_hours',
+  'get_available_slots',
+  'search_health_professionals',
+  'update_patient',
+  'search_patients_by_phone',
+  'create_patient',
+  'create_appointment',
+  'add_appointment_procedures',
+  'list_patient_appointments',
+  'cancel_appointment',
+  'submit_satisfaction',
+] as const;
+
+export type AiToolKey = (typeof AI_TOOL_KEYS)[number];
+
+export const AI_TOOL_POLICY_LEVELS = ['global', 'plan', 'tenant', 'unit'] as const;
+export type AiToolPolicyLevel = (typeof AI_TOOL_POLICY_LEVELS)[number];
+
+export const AI_TOOL_FALLBACK_MODES = [
+  'transfer_to_human',
+  'unavailable_message',
+] as const;
+export type AiToolFallbackMode = (typeof AI_TOOL_FALLBACK_MODES)[number];

package/src/configurations/index.ts

@@ -1,6 +1,8 @@
 export * from './opening-hours-slot.dto';
 export * from './update-clinic-configuration.dto';
 export * from './clinic-configuration.dto';
+export * from './ai-tool-policy.enums';
+export * from './ai-tool-policy.dto';
 export * from './plan-summary.dto';
 export * from './tenant-limits-summary.dto';
 export * from './configuration-tenant-summary.dto';

package/src/configurations/plan-summary.dto.ts

@@ -40,6 +40,9 @@ export class PlanSummaryDto {
   @ApiProperty({ description: 'Max procedures', example: 200 })
   maxProcedures: number;
 
+  @ApiProperty({ description: 'Monthly AI token allowance', example: 5000 })
+  monthlyAiTokens: number;
+
   @ApiPropertyOptional()
   createdAt?: Date;
 

package/src/tenants/consume-tenant-ai-tokens.dto.ts

@@ -0,0 +1,41 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsIn, IsInt, IsNotEmpty, IsOptional, IsString, Min } from 'class-validator';
+import { TenantAiTokenStateDto } from './tenant-ai-token-state.dto';
+
+export const TENANT_AI_TOKEN_CONSUMPTION_SOURCES = ['ai.request', 'ai.followup.generate'] as const;
+export type TenantAiTokenConsumptionSourceDto =
+  (typeof TENANT_AI_TOKEN_CONSUMPTION_SOURCES)[number];
+
+export class ConsumeTenantAiTokensDto {
+  @ApiProperty({ description: 'Tenant slug', example: 'clinic-alpha' })
+  @IsString()
+  @IsNotEmpty()
+  tenant: string;
+
+  @ApiProperty({ description: 'Tokens to consume', example: 420 })
+  @IsInt()
+  @Min(0)
+  tokens: number;
+
+  @ApiProperty({
+    description: 'Deterministic source of consumption',
+    enum: TENANT_AI_TOKEN_CONSUMPTION_SOURCES,
+  })
+  @IsIn(TENANT_AI_TOKEN_CONSUMPTION_SOURCES)
+  source: TenantAiTokenConsumptionSourceDto;
+
+  @ApiProperty({ description: 'Optional operation correlation id', required: false })
+  @IsOptional()
+  @IsString()
+  correlationId?: string;
+}
+
+export class ConsumeTenantAiTokensResponseDto extends TenantAiTokenStateDto {
+  @ApiProperty({ description: 'How many tokens were actually consumed', example: 420 })
+  @IsInt()
+  @Min(0)
+  consumed: number;
+
+  @ApiProperty({ description: 'True when the balance reached zero in this operation', example: false })
+  becameZero: boolean;
+}

package/src/tenants/index.ts

@@ -3,3 +3,7 @@ export * from './get-tenant-by-address.query.dto';
 export * from './tenant-public-by-address-response.dto';
 export * from './whatsapp-provider-kind.dto';
 export * from './tenant-slug.util';
+export * from './tenant-ai-token-state.dto';
+export * from './consume-tenant-ai-tokens.dto';
+export * from './recharge-tenant-ai-tokens.dto';
+export * from './renew-tenant-ai-tokens.dto';

package/src/tenants/recharge-tenant-ai-tokens.dto.ts

@@ -0,0 +1,27 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsInt, IsNotEmpty, IsOptional, IsString, Min } from 'class-validator';
+import { TenantAiTokenStateDto } from './tenant-ai-token-state.dto';
+
+export class RechargeTenantAiTokensDto {
+  @ApiProperty({ description: 'Tenant id (UUID)', example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' })
+  @IsString()
+  @IsNotEmpty()
+  tenantId: string;
+
+  @ApiProperty({ description: 'Amount of tokens to add', example: 10000 })
+  @IsInt()
+  @Min(1)
+  amount: number;
+
+  @ApiPropertyOptional({ description: 'Free text reason for audit', example: 'Recarga manual realizada pelo financeiro' })
+  @IsOptional()
+  @IsString()
+  reason?: string;
+}
+
+export class RechargeTenantAiTokensResponseDto extends TenantAiTokenStateDto {
+  @ApiProperty({ description: 'Recharge amount applied', example: 10000 })
+  @IsInt()
+  @Min(1)
+  added: number;
+}

package/src/tenants/renew-tenant-ai-tokens.dto.ts

@@ -0,0 +1,16 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsInt, IsOptional, IsString, Min } from 'class-validator';
+
+export class RenewTenantAiTokensDto {
+  @ApiPropertyOptional({ description: 'Optional tenant id to renew one tenant only' })
+  @IsOptional()
+  @IsString()
+  tenantId?: string;
+}
+
+export class RenewTenantAiTokensResponseDto {
+  @ApiPropertyOptional({ description: 'How many tenants were renewed', example: 12 })
+  @IsInt()
+  @Min(0)
+  renewedCount: number;
+}

package/src/tenants/tenant-ai-token-state.dto.ts

@@ -0,0 +1,50 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsBoolean, IsDateString, IsInt, IsNotEmpty, IsOptional, IsString, Min } from 'class-validator';
+
+export class TenantAiTokenStateDto {
+  @ApiProperty({ description: 'Tenant slug', example: 'clinic-alpha' })
+  @IsString()
+  @IsNotEmpty()
+  tenant: string;
+
+  @ApiProperty({ description: 'Current remaining AI tokens', example: 2400 })
+  @IsInt()
+  @Min(0)
+  currentBalance: number;
+
+  @ApiProperty({ description: 'Monthly allowance configured for current cycle', example: 5000 })
+  @IsInt()
+  @Min(0)
+  monthlyAllowance: number;
+
+  @ApiProperty({ description: 'Whether IA is blocked for this tenant', example: false })
+  @IsBoolean()
+  blocked: boolean;
+
+  @ApiProperty({ description: 'Current cycle start timestamp', example: '2026-04-01T00:00:00.000Z' })
+  @IsDateString()
+  cycleStartedAt: string;
+
+  @ApiProperty({ description: 'Next monthly renewal timestamp', example: '2026-05-01T00:00:00.000Z' })
+  @IsDateString()
+  nextRenewalAt: string;
+
+  @ApiProperty({ description: 'Plan recurrence in days used for renewal', example: 30 })
+  @IsInt()
+  @Min(1)
+  recurrenceDays: number;
+
+  @ApiProperty({ description: 'True when balance is currently greater than zero', example: true })
+  @IsBoolean()
+  canUseAi: boolean;
+
+  @ApiProperty({ description: 'Last consumption timestamp', required: false })
+  @IsOptional()
+  @IsDateString()
+  lastConsumedAt?: string;
+
+  @ApiProperty({ description: 'Last recharge timestamp', required: false })
+  @IsOptional()
+  @IsDateString()
+  lastRechargedAt?: string;
+}