agents-infrastructure/.claude/skills/alicloud-oss

Alibaba Cloud OSS (Object Storage Service)

Manage Alibaba Cloud OSS using the @alicloud/oss20190517 TypeScript SDK. Use when working with object storage buckets, objects, multipart uploads, bucket configurations (lifecycle, versioning, CORS, encryption, replication, WORM), live streaming channels, and static website hosting. Covers all 90 APIs of the OSS 2019-05-17 version.

General Instructions

• SDK Package: @alicloud/oss20190517 (with @alicloud/openapi-client, @alicloud/gateway-oss, @alicloud/gateway-spi, @alicloud/tea-util, @alicloud/openapi-util, @alicloud/tea-typescript)
• Authentication: Use environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET
• Client Init: Create client with regionId — endpoint is auto-resolved to oss-{regionId}.aliyuncs.com
• API Style: RESTful — bucket and key are function arguments, not in Request objects
• Models: All models (Request/Response) are exported from the main client module
• Pagination: Marker-based (marker/nextMarker or continuationToken/nextContinuationToken), not page numbers
• Streaming: Object upload/download uses Node.js Readable streams for the body field
• Error Handling: Catch errors with error.code (e.g., NoSuchBucket, NoSuchKey, AccessDenied)

Quick Reference

Read references/quickstart.md for installation, authentication, endpoints, storage classes, ACL values, pagination patterns, and error codes.

API Reference by Domain

The SDK provides 90 APIs organized into 6 functional domains:

Bucket Management (11 APIs)

Create, list, delete, and query bucket information, ACL, location, and regions. List objects in buckets. → Read references/bucket.md for: putBucket, listBuckets, getBucketInfo, getBucketLocation, getBucketAcl, putBucketAcl, deleteBucket, describeRegions, listObjects, listObjectsV2, listObjectVersions

Bucket Configuration (33 APIs)

Configure bucket lifecycle, versioning, CORS, logging, website hosting, referer, encryption, request payment, transfer acceleration, tags, inventory, and policy. → Read references/bucket-config.md for: getBucketLifecycle, putBucketLifecycle, deleteBucketLifecycle, getBucketVersioning, putBucketVersioning, getBucketCors, putBucketCors, deleteBucketCors, getBucketLogging, putBucketLogging, deleteBucketLogging, getBucketWebsite, putBucketWebsite, deleteBucketWebsite, getBucketReferer, putBucketReferer, getBucketEncryption, putBucketEncryption, deleteBucketEncryption, getBucketRequestPayment, putBucketRequestPayment, getBucketTransferAcceleration, putBucketTransferAcceleration, getBucketTags, putBucketTags, deleteBucketTags, getBucketInventory, listBucketInventory, putBucketInventory, deleteBucketInventory, getBucketPolicy, putBucketPolicy, deleteBucketPolicy

Bucket Replication & WORM (10 APIs)

Cross-region and same-region data replication, replication progress monitoring, and compliance retention (WORM) policies. → Read references/bucket-replication.md for: getBucketReplication, getBucketReplicationLocation, getBucketReplicationProgress, putBucketReplication, deleteBucketReplication, initiateBucketWorm, getBucketWorm, abortBucketWorm, completeBucketWorm, extendBucketWorm

Object Operations (20 APIs)

Upload, download, copy, delete, append, head, meta, ACL, symlink, tagging, restore, select, and CORS preflight. → Read references/object.md for: putObject, getObject, copyObject, appendObject, deleteObject, deleteMultipleObjects, headObject, getObjectMeta, postObject, restoreObject, selectObject, createSelectObjectMeta, optionObject, getObjectAcl, putObjectAcl, getSymlink, putSymlink, getObjectTagging, putObjectTagging, deleteObjectTagging

Multipart Upload (7 APIs)

Multipart upload operations for large files (>100MB recommended, >5GB required). Minimum part size 100KB (last part exempt). → Read references/multipart.md for: initiateMultipartUpload, uploadPart, uploadPartCopy, completeMultipartUpload, abortMultipartUpload, listMultipartUploads, listParts

Live Channel (9 APIs)

RTMP-based live streaming channel management, status monitoring, history, and VOD playlist generation. → Read references/live-channel.md for: putLiveChannel, getLiveChannelInfo, getLiveChannelStat, getLiveChannelHistory, listLiveChannel, putLiveChannelStatus, deleteLiveChannel, postVodPlaylist, getVodPlaylist

Common Workflows

Read references/workflows.md for 8 step-by-step workflows:

1. Create bucket and upload object
2. Multipart upload for large files
3. Configure bucket lifecycle rules
4. Enable cross-region replication
5. Static website hosting
6. WORM compliance retention
7. Restore archive objects
8. Server-side encryption

Key Patterns

Client Initialization

import Client from '@alicloud/oss20190517';
import { Config } from '@alicloud/openapi-client';

const client = new Client(new Config({
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
  accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
  regionId: 'cn-hangzhou',
}));

Upload Object

import Client, { PutObjectRequest } from '@alicloud/oss20190517';
import { Readable } from 'stream';

await client.putObject('my-bucket', 'path/to/file.txt', new PutObjectRequest({
  body: Readable.from(Buffer.from('content')),
  contentType: 'text/plain',
}));

Download Object

import Client, { GetObjectRequest } from '@alicloud/oss20190517';

const { body } = await client.getObject('my-bucket', 'path/to/file.txt', new GetObjectRequest({}));
const chunks: Buffer[] = [];
for await (const chunk of body.body as Readable) {
  chunks.push(Buffer.from(chunk));
}
const content = Buffer.concat(chunks);

List Objects (Paginated)

import Client, { ListObjectsV2Request } from '@alicloud/oss20190517';

let token: string | undefined;
const all: any[] = [];
do {
  const { body } = await client.listObjectsV2('my-bucket', new ListObjectsV2Request({
    maxKeys: 1000, prefix: 'data/', continuationToken: token,
  }));
  all.push(...(body.contents || []));
  token = body.isTruncated ? body.nextContinuationToken || undefined : undefined;
} while (token);

Delete Multiple Objects

import Client, { DeleteMultipleObjectsRequest, Delete, DeleteObjectsRequestObject } from '@alicloud/oss20190517';

await client.deleteMultipleObjects('my-bucket', new DeleteMultipleObjectsRequest({
  delete: new Delete({
    object: ['a.txt', 'b.txt'].map(k => new DeleteObjectsRequestObject({ key: k })),
    quiet: true,
  }),
}));

Scripts

• scripts/setup_client.ts — Reusable client factory with region, STS, and custom endpoint support
• scripts/examples.ts — 18 ready-to-use functions covering bucket, object, multipart, lifecycle, CORS, tags, symlink, and restore operations

Important Notes

• Object key: No leading slash. Use path/to/file.txt, not /path/to/file.txt
• Bucket names: Globally unique, 3-63 chars, lowercase letters/numbers/hyphens
• Max object size: 5 GB for single PUT, use multipart for larger files
• Multipart minimum: Each part ≥ 100KB (except last part), max 10,000 parts
• Archive restore: Takes 1 minute (Archive) to hours (Deep Cold Archive)
• WORM lock: completeBucketWorm is irreversible — data cannot be deleted until retention expires
• Versioning: Once enabled, can only be suspended (not disabled)
• Replication: Source and destination buckets must be in different regions (for CRR)