reset_usage_limit_entity

Instructions

Implementation Reference

• src/services/limits.service.ts:217-231 (handler)

  Service method that executes the reset logic. Validates inputs and sends POST request to /policies/usage-limits/{limitId}/entities/reset with entity_id in the body.

  async resetUsageLimitEntity(
  	limitId: string,
  	entityId: string,
  ): Promise<{ success: boolean }> {
  	if (!limitId?.trim()) {
  		throw new Error("Usage limit ID is required");
  	}
  	if (!entityId?.trim()) {
  		throw new Error("Entity ID is required");
  	}
  	return this.post<{ success: boolean }>(
  		`/policies/usage-limits/${this.encodePathSegment(limitId)}/entities/reset`,
  		{ entity_id: entityId },
  	);
  }

• src/tools/limits.tools.ts:156-159 (schema)

  Zod schema for reset_usage_limit_entity tool input: requires limit_id and entity_id strings.

  resetUsageLimitEntity: {
  	limit_id: z.string().describe("Usage limit policy ID"),
  	entity_id: z.string().describe("Entity ID to reset usage for"),
  },

• src/tools/limits.tools.ts:536-561 (registration)

  Tool registration using server.tool() with name 'reset_usage_limit_entity', description, schema, and handler that calls the service method and returns a success message.

  server.tool(
  	"reset_usage_limit_entity",
  	"Reset tracked usage for one entity under a usage limit. This changes accumulated usage for that entity only; use list_usage_limit_entities to confirm the target first.",
  	LIMITS_TOOL_SCHEMAS.resetUsageLimitEntity,
  	async (params) => {
  		await service.limits.resetUsageLimitEntity(
  			params.limit_id,
  			params.entity_id,
  		);
  		return {
  			content: [
  				{
  					type: "text",
  					text: JSON.stringify(
  						{
  							message: `Successfully reset usage for entity "${params.entity_id}" on limit "${params.limit_id}"`,
  							success: true,
  						},
  						null,
  						2,
  					),
  				},
  			],
  		};
  	},
  );

• src/services/base.service.ts:34-162 (helper)

  BaseService class providing get/post/put/delete HTTP methods, authentication, URL building, error handling, and logging used by LimitsService.

  export class BaseService {
  	protected readonly apiKey: string;
  	protected readonly baseUrl: string;
  	protected readonly timeout = 30000;
  
  	constructor(apiKeyOverride?: string) {
  		// Use provided API key or fall back to environment variable
  		const apiKey = apiKeyOverride ?? process.env.PORTKEY_API_KEY;
  		if (!apiKey) {
  			throw new Error("PORTKEY_API_KEY environment variable is not set");
  		}
  		this.apiKey = apiKey;
  
  		// Configurable base URL with validation
  		const baseUrl = process.env.PORTKEY_BASE_URL ?? DEFAULT_BASE_URL;
  		validateUrl(baseUrl);
  		this.baseUrl = baseUrl;
  	}
  
  	protected encodePathSegment(value: string): string {
  		return encodeURIComponent(value);
  	}
  
  	private buildUrl(path: string, params?: object): string {
  		return `${this.baseUrl}${path}${buildQueryString(params)}`;
  	}
  
  	private buildHeaders(method: HttpMethod): Record<string, string> {
  		const headers: Record<string, string> = {
  			"x-portkey-api-key": this.apiKey,
  			Accept: "application/json",
  		};
  
  		if (method === "POST" || method === "PUT") {
  			headers["Content-Type"] = "application/json";
  		}
  
  		return headers;
  	}
  
  	private serializeBody(body: unknown): string | undefined {
  		return body ? JSON.stringify(body) : undefined;
  	}
  
  	private async executeRequest<T>(
  		method: HttpMethod,
  		path: string,
  		options: ExecuteRequestOptions = {},
  	): Promise<T> {
  		const requestId = crypto.randomUUID();
  		const url = this.buildUrl(path, options.params);
  		const startTime = Date.now();
  
  		Logger.debug("HTTP request started", {
  			requestId,
  			method,
  			path,
  			metadata: { url },
  		});
  
  		try {
  			const response = await fetchWithTimeout(url, {
  				method,
  				headers: this.buildHeaders(method),
  				body: this.serializeBody(options.body),
  				timeout: this.timeout,
  			});
  
  			const duration_ms = Date.now() - startTime;
  
  			if (!response.ok) {
  				const apiError = await parseErrorResponse(response);
  				Logger.error("HTTP request failed", {
  					requestId,
  					method,
  					path,
  					statusCode: response.status,
  					duration_ms,
  					error: apiError.message,
  				});
  				throw new FetchError(apiError.message, response.status, apiError);
  			}
  
  			Logger.info("HTTP request completed", {
  				requestId,
  				method,
  				path,
  				statusCode: response.status,
  				duration_ms,
  			});
  
  			if (options.allowNoContent && response.status === 204) {
  				return {} as T;
  			}
  
  			return response.json() as Promise<T>;
  		} catch (error) {
  			const duration_ms = Date.now() - startTime;
  			// Only log network/system errors (TypeError, AbortError, etc.)
  			// FetchError from HTTP failures is already logged above
  			if (!(error instanceof FetchError)) {
  				Logger.error("HTTP request error", {
  					requestId,
  					method,
  					path,
  					duration_ms,
  					error: error instanceof Error ? error.message : String(error),
  				});
  			}
  			throw error;
  		}
  	}
  
  	protected async get<T>(path: string, params?: object): Promise<T> {
  		return this.executeRequest<T>("GET", path, { params });
  	}
  
  	protected async post<T>(path: string, body?: unknown): Promise<T> {
  		return this.executeRequest<T>("POST", path, { body });
  	}
  
  	protected async put<T>(path: string, body?: unknown): Promise<T> {
  		return this.executeRequest<T>("PUT", path, { body });
  	}
  
  	protected async delete<T>(path: string): Promise<T> {
  		return this.executeRequest<T>("DELETE", path, { allowNoContent: true });
  	}
  }