@lark-apaas/action-plugin-common

Common utilities for aPaaS action plugin development — provides error types and platform API error handling.

Install

npm install @lark-apaas/action-plugin-common

API

Error Classes

RateLimitError

Thrown when a plugin encounters rate limiting or quota exhaustion. The platform identifies this error by code === 'RATE_LIMIT_EXCEEDED' and passes rateLimitCode / rateLimitMessage to the business layer.

import { RateLimitError } from '@lark-apaas/action-plugin-common';

// Quota exhausted
throw new RateLimitError('quota_exceeded', '本月配额已用完，请下月再试');

// QPS throttling
throw new RateLimitError('qps_limit', '请求过于频繁，请稍后再试');

PlatformApiError

Wraps non-rate-limit platform API errors with plugin/action context.

import { PlatformApiError } from '@lark-apaas/action-plugin-common';

throw new PlatformApiError(
  'API call failed',
  'my-plugin',
  'myAction',
  errorOutput,
);

Error Handling Utilities

handlePlatformError(output, pluginName, actionName)

Inspects a platform API error output and throws the appropriate error:

• RateLimitError for ResourceExhausted errors
• PlatformApiError for all others

import { handlePlatformError } from '@lark-apaas/action-plugin-common';

// Streaming
if (chunk.success !== true) {
  handlePlatformError(chunk.chunkOutput, 'ai-text-generate', 'textGenerate');
}

// Unary
if (result.data.success === false) {
  handlePlatformError(result.data.output, 'ai-text-to-image', 'textToImage');
}

extractRateLimitError(output)

Returns a RateLimitError instance if the output is a rate-limit error, otherwise null.

import { extractRateLimitError } from '@lark-apaas/action-plugin-common';

const rateLimitError = extractRateLimitError(chunk.chunkOutput);
if (rateLimitError) {
  throw rateLimitError;
}

isRateLimitError(output)

Checks whether a PlatformErrorOutput object represents a rate-limit error (code === 'ResourceExhausted').

isRateLimitErrorInstance(error)

Checks whether an error is an instance of RateLimitError.

Types

import type {
  CallApiResponse,
  PlatformErrorDetail,
  PlatformErrorOutput,
  SSEMessage,
  StreamCallChunk,
} from '@lark-apaas/action-plugin-common';

| Type | Description | | --- | --- | | CallApiResponse<T> | Response shape for unary platform API calls | | StreamCallChunk | Chunk shape for streaming platform API calls | | SSEMessage | SSE message structure | | PlatformErrorOutput | Platform API error output | | PlatformErrorDetail | Error detail with business code and message |

Constants

• RATE_LIMIT_ERROR_CODE — 'ResourceExhausted'

License

MIT