@comchatx/cx-s3-storage 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ComChatX
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,19 @@
1
- # Temporary Holding Version
1
+ cx stores images and other files in your own bucket, each with a public address a listing can use as its main image, and can list, read, copy and delete them. Amazon S3, Cloudflare R2 and other S3-compatible storage all work.
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Some things you can ask:
4
+
5
+ - Store these images in my bucket's listings folder, and give me each one's link.
6
+ - Which images are in my bucket's listings folder?
7
+ - Copy last year's images in listings to an archive folder, then delete the originals.
8
+
9
+ ## Connecting your bucket
10
+
11
+ On the plugin's Settings, enter the endpoint, bucket, region, Access key ID, Secret access key and public address. Your provider's guide shows where to find each one. A key limited to one bucket keeps cx to that bucket. Your keys stay with ComChatX and are never given to cx.
12
+
13
+ ## What it costs
14
+
15
+ Nothing on ComChatX. Your provider bills your own account as usual.
16
+
17
+ ## What it needs
18
+
19
+ It installs with cx-sources, through which cx reaches every data source.
@@ -0,0 +1,19 @@
1
+ cx 把图片和其他文件存进你自己的存储桶,每个文件都有公开地址,可以填作 listing 的主图链接;也能列出、读取、复制和删除桶里的文件。Amazon S3、Cloudflare R2 等兼容 S3 的存储都能用。
2
+
3
+ 你可以这样问:
4
+
5
+ - 把这几张图存进存储桶的 listings 文件夹,再告诉我每张的链接。
6
+ - 存储桶的 listings 文件夹里有哪些图片?
7
+ - 把 listings 里去年的旧图复制到 archive 文件夹,再删掉原图。
8
+
9
+ ## 连接存储桶
10
+
11
+ 在插件的「设置」里填写端点、存储桶、区域、Access key ID、Secret access key 和公开地址,各项的获取方法见服务商的指南。密钥只能访问一个存储桶时,cx 也只能用这一个。你的密钥保存在 ComChatX,不会交给 cx。
12
+
13
+ ## 费用
14
+
15
+ ComChatX 不收费,服务商照常向你自己的账号收费。
16
+
17
+ ## 需要
18
+
19
+ 它会和 cx-sources 一起安装,cx 通过 cx-sources 使用所有数据源。
package/package.json CHANGED
@@ -1,6 +1,111 @@
1
1
  {
2
2
  "name": "@comchatx/cx-s3-storage",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Stores your images in your own bucket, with links for listings.",
5
+ "license": "MIT",
6
+ "author": "ComChatX",
7
+ "homepage": "https://github.com/comchatx/cx-s3-storage#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/comchatx/cx-s3-storage.git"
11
+ },
12
+ "bugs": "https://github.com/comchatx/cx-s3-storage/issues",
13
+ "keywords": [
14
+ "pi-package"
15
+ ],
16
+ "type": "module",
17
+ "pi": {
18
+ "skills": [
19
+ "./skills"
20
+ ]
21
+ },
22
+ "files": [
23
+ "skills",
24
+ "README.zh-CN.md"
25
+ ],
26
+ "scripts": {
27
+ "typecheck": "tsc --noEmit",
28
+ "test": "vitest run"
29
+ },
30
+ "comchatx": {
31
+ "about": "把商品图片存进你自己的存储桶,生成 listing 用的链接。",
32
+ "mark": {
33
+ "line": "layers"
34
+ },
35
+ "section": "data",
36
+ "order": 22,
37
+ "skills": {
38
+ "s3": {
39
+ "zh": "列出、读取、写入、复制和删除存储桶里的文件,分段上传大文件,并给出文件的公开地址,例如 listing 图片的链接。"
40
+ }
41
+ },
42
+ "source": {
43
+ "name": "s3-storage",
44
+ "help": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html",
45
+ "aspects": {},
46
+ "fields": {
47
+ "endpoint": {
48
+ "label": {
49
+ "en": "Endpoint",
50
+ "zh": "端点"
51
+ },
52
+ "help": {
53
+ "en": "For example https://s3.us-east-1.amazonaws.com.",
54
+ "zh": "例如 https://s3.us-east-1.amazonaws.com。"
55
+ }
56
+ },
57
+ "bucket": {
58
+ "label": {
59
+ "en": "Bucket",
60
+ "zh": "存储桶"
61
+ }
62
+ },
63
+ "region": {
64
+ "label": {
65
+ "en": "Region",
66
+ "zh": "区域"
67
+ },
68
+ "help": {
69
+ "en": "For example us-east-1, or auto for Cloudflare R2.",
70
+ "zh": "例如 us-east-1,Cloudflare R2 填 auto。"
71
+ }
72
+ },
73
+ "key_id": {
74
+ "label": {
75
+ "en": "Access key ID",
76
+ "zh": "Access key ID"
77
+ },
78
+ "help": {
79
+ "en": "cx can use only the buckets this key reaches.",
80
+ "zh": "cx 只能使用这个密钥能访问的存储桶。"
81
+ }
82
+ },
83
+ "secret_key": {
84
+ "label": {
85
+ "en": "Secret access key",
86
+ "zh": "Secret access key"
87
+ }
88
+ },
89
+ "public_base": {
90
+ "label": {
91
+ "en": "Public address",
92
+ "zh": "公开地址"
93
+ },
94
+ "help": {
95
+ "en": "Where anyone can open your bucket's files, for example https://images.example.com.",
96
+ "zh": "存储桶文件对外公开的网址,例如 https://images.example.com。"
97
+ }
98
+ }
99
+ }
100
+ }
101
+ },
102
+ "dependencies": {
103
+ "cx-sources": "^0.1.3"
104
+ },
105
+ "devDependencies": {
106
+ "@earendil-works/pi-coding-agent": "1.4.0",
107
+ "@types/node": "26.2.0",
108
+ "typescript": "7.0.2",
109
+ "vitest": "4.1.11"
110
+ }
111
+ }
@@ -0,0 +1,47 @@
1
+ ---
2
+ name: s3
3
+ description: The seller's own S3-compatible object storage (Amazon S3, Cloudflare R2, Backblaze B2, Wasabi or any provider that serves the S3 API) through the S3 REST API, signed with the seller's key — list, read, write, copy and delete objects, multipart uploads, and the public address of a stored object, such as an image's URL for a listing. Use before the first call that reads or changes the seller's own bucket. Needs cx-sources; if no cx-sources skill is listed, it is not installed, and the seller installs it in Plugins.
4
+ ---
5
+
6
+ S3 is an open door through `cx raw`; read cx-sources first. The door sends any S3 request to the endpoint the seller saved, its method, path, query, headers and body as written, signs it with the seller's key, and lands the provider's reply as the provider gave it. It is what a local S3 client does, and the seller's key decides which buckets and objects a request reaches. The platform charges nothing; the provider bills the seller's own account. If S3 is off, the seller turns its plugin on in Plugins.
7
+
8
+ ```sh
9
+ cx raw s3-storage --origin field:endpoint --method GET --path /<bucket> --query list-type=2 --query prefix=listings/
10
+ ```
11
+
12
+ The provider's reference is the S3 API's: <https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations_Amazon_Simple_Storage_Service.html>.
13
+
14
+ ## Requests
15
+
16
+ - Every request names `--origin field:endpoint`, the door's own name for the endpoint the seller saved; it is not an address, and the door sends only there. A request naming an address, or no origin, is refused. Each request in the table below takes it too.
17
+ - Paths are path-style: the bucket first, then the key, `/<bucket>/<key>`. The bucket the seller saved is theirs to use by default; another bucket on the same endpoint is reached when the key allows it.
18
+ - Each `--query` is one `name=value` pair, sent in order; an operation's word with no value is `name=`, as `uploads=`.
19
+ - The door writes `x-amz-date`, `x-amz-content-sha256` and `authorization`; a request naming either of the first two is refused. A `GET` or `HEAD` with a body, `TRACE`, `CONNECT` and `TRACK` are not sent.
20
+ - A key goes as written, percent-encoded: a space as `%20`, a folder marker with its trailing `/`. A segment `.` or `..` is refused.
21
+ - A request body is at most 10 MiB (10,485,760 bytes); a larger `--body` is refused before anything is sent, naming the bound, and a larger file goes in parts.
22
+
23
+ | Task | Request |
24
+ |---|---|
25
+ | List | `--method GET --path /<bucket> --query list-type=2 [--query prefix=<p>] [--query continuation-token=<t>]` |
26
+ | Read | `--method GET --path /<bucket>/<key> --output <file>`; `--header range=bytes=0-1023` reads part |
27
+ | Check | `--method HEAD --path /<bucket>/<key>` |
28
+ | Write | `--method PUT --path /<bucket>/<key> --header content-type=<type> --body <file>` |
29
+ | Copy | `--method PUT --path /<bucket>/<new key> --header x-amz-copy-source=/<bucket>/<key>` |
30
+ | Delete | `--method DELETE --path /<bucket>/<key>` |
31
+
32
+ A list answers XML; past 1,000 keys it carries `NextContinuationToken`, which the next list sends as `continuation-token`.
33
+
34
+ ## Multipart
35
+
36
+ `POST /<bucket>/<key>?uploads=` answers an `UploadId`; `PUT ...?partNumber=<n>&uploadId=<id>` sends a part; `POST ...?uploadId=<id>` with the parts' XML completes it, and `DELETE ...?uploadId=<id>` abandons it. Each part is under the body bound, and S3 takes a part under 5 MiB only as the last. A part copied from an object already stored, `x-amz-copy-source` with `x-amz-copy-source-range` and no body, has no bound here.
37
+
38
+ ## The public address
39
+
40
+ A `PUT` with no query into the saved bucket, a write or a copy, answers with `x-cx-public-url` beside the provider's headers: the seller's public base and the key, where the object is reachable once the provider serves that base publicly. Another party that fetches by URL, such as Amazon for a listing's main image in `main_product_image_locator`'s `media_location`, takes that address. The provider never sees the header.
41
+
42
+ ## Replies
43
+
44
+ - A `2xx` lands as an answer; any other status is a failure with the provider's XML error as vendor text, and the reply kept.
45
+ - A `503` (`SlowDown`) or `429` is the provider throttling: the door adds no wait and retries nothing.
46
+ - A redirect is not followed: a `301` `PermanentRedirect` names a bucket in another region than the saved endpoint's.
47
+ - The box holds no key, so it signs nothing itself: no presigned URL is made here.