aliyun-api-ref

name	aliyun-api-ref
description	Alibaba Cloud API reference for developing aero-cli. Use this skill when adding new cloud provider features, fixing API calls, or extending FC/RDS/Redis/OSS/DNS/VPC integrations. Contains SDK usage patterns, API signatures, and error handling conventions specific to this project.

Alibaba Cloud API Development Reference

When to use this skill

Use this skill when:

• Adding or modifying Alibaba Cloud API calls in src/providers/
• Implementing new cloud service integrations (FC, RDS, Redis, OSS, DNS, VPC)
• Debugging API errors or handling new error codes
• Understanding SDK constructor patterns and authentication flow
• Working with pagination, retry logic, or async polling patterns

Project Architecture

src/providers/       # Cloud service provider modules
  fc.ts              # Function Compute 3.0 (deploy, invoke, versions, aliases)
  infra.ts           # RDS Serverless (database provisioning)
  redis.ts           # Tair/Redis Serverless KV (cache provisioning)
  oss.ts             # Object Storage Service (static site deploy)
  domain.ts          # DNS + FC custom domain binding
  ssl.ts             # Let's Encrypt ACME + FC HTTPS binding
  vpc.ts             # VPC / VSwitch / SecurityGroup management
  logs.ts            # SLS log streaming
src/utils/
  sdk.ts             # Shared SDK constructor resolver + FC client factory
  retry.ts           # Exponential backoff retry wrapper
  config.ts          # Auth (AK/SK) and project config management
  errors.ts          # Error classification (conflict, not-found, etc.)

SDK Usage Patterns

Constructor Resolution

All Alibaba Cloud SDKs are loaded via resolveSdkCtor() to handle ESM/CJS interop:

import Vpc, * as $Vpc from '@alicloud/vpc20160428';
import { resolveSdkCtor } from '../utils/sdk';

const VpcClientCtor = resolveSdkCtor<Vpc>(Vpc, '@alicloud/vpc20160428');

Client Instantiation

Each provider creates its client with @alicloud/openapi-client Config:

import * as $OpenApi from '@alicloud/openapi-client';

const client = new VpcClientCtor(new $OpenApi.Config({
  accessKeyId: auth.ak,
  accessKeySecret: auth.sk,
  regionId,
  endpoint: `vpc.${regionId}.aliyuncs.com`
}));

Shared FC Client

FC client creation is centralized in utils/sdk.ts:

import { createSharedFcClient } from '../utils/sdk';

const { auth, client } = createSharedFcClient();
// or with explicit auth:
const { client } = createSharedFcClient(authConfig);

Authentication

Credentials are stored in ~/.ali-cli/auth.json (mode 0o600):

interface AuthConfig {
  accountId: string;  // Alibaba Cloud main account ID
  ak: string;         // AccessKey ID
  sk: string;         // AccessKey Secret
  region: string;     // Default region (e.g. cn-hangzhou)
}

Access via Config.requireAuth() or Config.getAuth().

Error Handling Conventions

Error Classification (utils/errors.ts)

// Check if error is a "resource already exists" conflict
isConflictError(err)  // matches: AlreadyExists, Conflict, Duplicate, Exist

// Format error message for display
formatErrorMessage(err)  // extracts .message from unknown error

Retry Pattern (utils/retry.ts)

import { withRetry } from '../utils/retry';

const result = await withRetry(
  () => client.someApiCall(request),
  { maxAttempts: 3, baseDelayMs: 1000 }
);

Retries on: Throttling, timeout, ECONNRESET, service unavailable.

Empty Catch Blocks

When intentionally ignoring errors, always add a comment explaining why:

} catch { /* role check may fail due to permissions, proceed to create attempt */ }

Pagination Pattern

Use bounded for loops with MAX_PAGES guard, never while(true):

const MAX_PAGES = 50;
for (let page = 0; page < MAX_PAGES; page += 1) {
  const response = await client.listSomething(new ListRequest({
    limit: 100,
    nextToken
  }));
  const rows = response.body?.items || [];
  results.push(...rows);
  nextToken = response.body?.nextToken;
  if (!nextToken || rows.length === 0) break;
}

API Quick Reference

Detailed API tables are in references/:

• references/ref_fc_apis.md — Function Compute 3.0 (86 APIs, version 2023-03-30)
• references/ref_rds_apis.md — RDS instance/database/account management
• references/ref_redis_apis.md — Redis/Tair instance management (146 APIs, version 2015-01-01)
• references/ref_oss_apis.md — Object Storage bucket/object operations
• references/ref_dns_apis.md — Cloud DNS domain/record management (235 APIs, version 2015-01-09)

Key APIs Used by This Project

Provider	Primary APIs	SDK Package
FC	CreateFunction, UpdateFunction, InvokeFunction, PublishFunctionVersion, UpdateAlias, CreateCustomDomain	@alicloud/fc20230330
RDS	CreateDBInstance, DescribeDBInstances, CreateAccount, CreateDatabase, DescribeAvailableZones	@alicloud/rds20140815
Redis	CreateTairInstance, DescribeInstances, CreateAccount, ResetAccountPassword	@alicloud/r-kvstore20150101
OSS	putBucket, put (object), list, getBucketInfo	ali-oss
DNS	AddDomainRecord, UpdateDomainRecord, DeleteDomainRecord, DescribeSubDomainRecords	@alicloud/alidns20150109
VPC	DescribeVpcs, CreateVSwitch, DescribeVSwitches	@alicloud/vpc20160428
ECS	CreateSecurityGroup, AuthorizeSecurityGroup	@alicloud/ecs20140526
SLS	GetLogs	@alicloud/sls20201230

Provider Implementation Checklist

When adding a new provider or extending an existing one:

1. Use resolveSdkCtor() for SDK constructor resolution
2. Create client with proper endpoint, connectTimeout, readTimeout
3. Use withRetry() for API calls that may face transient failures
4. Use bounded pagination (never while(true))
5. Classify errors with isConflictError() where applicable
6. Add comments to any intentionally empty catch blocks
7. Store sensitive outputs (passwords, connection strings) in project.envs
8. Mask credentials in CLI output via maskConnectionString()