name	cf-sharepage
description	Use when a third-party agent needs to publish, update, or verify a single-file HTML page through an existing cf-sharepage API endpoint; use for API clients, share links, raw index.html uploads, bearer publish tokens, or bearer update tokens.

cf-sharepage API Client Skill

Overview

Use this skill to call an existing cf-sharepage service from another agent or client. The service publishes one raw HTML document per page version and returns share URLs that serve that document as an SPA fallback.

This skill is for API usage only. Do not use it for developing, deploying, or locally running the cf-sharepage service implementation.

Required Inputs

Before calling the API, identify:

baseUrl: the deployed service origin, for example https://share.example.com.
HTML input: a file path, generated HTML string, or raw HTML bytes.
For page creation: a publish bearer token.
For page updates: the existing update bearer token and either the update URL or both period and pageId.

Ask one focused question if any required input is missing.

Secret Handling

Treat publish tokens and update tokens as secrets.
Send tokens only in the Authorization: Bearer ... header.
Do not put tokens in URLs, logs, committed files, generated HTML, or browser storage.
Do not print returned update tokens in the final response unless the user needs them for future updates.
If returning an update token, label it clearly as secret.

API Contract

Create Page

POST /app
Authorization: Bearer <publishToken>
Content-Type: text/html

<!doctype html><html>...</html>

Expected success response:

{
  "pageId": "public-random-id",
  "period": "YYYYMM",
  "version": 0,
  "shareUrl": "https://.../s/YYYYMM/{pageId}",
  "updateToken": "secret-update-token"
}

Store period, pageId, shareUrl, and updateToken in the caller's approved secret/state location if future updates are needed.

Update Page

POST /app/YYYYMM/{pageId}/versions
Authorization: Bearer <updateToken>
Content-Type: text/html

<!doctype html><html>...</html>

Expected success response:

{
  "pageId": "public-random-id",
  "period": "YYYYMM",
  "version": 1,
  "shareUrl": "https://.../s/YYYYMM/{pageId}",
  "versionUrl": "https://.../s/YYYYMM/{pageId}/versions/1"
}

Read Published Pages

GET /s/YYYYMM/{pageId}
GET /s/YYYYMM/{pageId}/any/spa/path
GET /s/YYYYMM/{pageId}/versions/{version}
GET /s/YYYYMM/{pageId}/versions/{version}/any/spa/path

Latest URLs serve the current publish/index.html. Fixed-version URLs serve immutable historical index.html versions.

HTML Requirements

Send raw HTML bytes, not JSON, multipart form data, zip files, directories, or bundled asset folders.
Use Content-Type: text/html or text/html; charset=utf-8.
Body must be non-empty and start like an HTML document near the beginning, such as <!doctype html> or <html>.
V1 stores one index.html only. Inline assets or reference externally hosted assets if the page needs CSS, JS, images, or fonts.

Bash curl Client Pattern

Use environment variables for reusable values and secrets where possible.

BASE_URL: service origin, for example https://share.example.com.
PUBLISH_TOKEN: bearer token for creating pages.
UPDATE_TOKEN: bearer token returned by the create response for later updates.
PERIOD, PAGE_ID, and VERSION: values from API responses.

Create From A File

curl -X POST "$BASE_URL/app" \
  -H "Authorization: Bearer $PUBLISH_TOKEN" \
  -H "Content-Type: text/html" \
  --data-binary "@index.html"

Update From A File

curl -X POST "$BASE_URL/app/$PERIOD/$PAGE_ID/versions" \
  -H "Authorization: Bearer $UPDATE_TOKEN" \
  -H "Content-Type: text/html" \
  --data-binary "@index.html"

Verify Publication

curl -i "$BASE_URL/s/$PERIOD/$PAGE_ID"

curl -i "$BASE_URL/s/$PERIOD/$PAGE_ID/versions/$VERSION"

Response Handling

Status	Meaning	Client action
200	Share URL served successfully	Verify expected HTML content if needed
201	Create or update succeeded	Store returned metadata securely
400	Invalid HTML body or max versions reached	Check HTML shape or version cap
401	Missing or invalid bearer token	Re-check token source and header
404	Unknown route, page, or version	Check `period`, `pageId`, version, and route shape
413	HTML body exceeds service limit	Reduce size or ask service owner about limit changes
415	Unsupported content type	Send raw HTML with `Content-Type: text/html`
500	Unexpected service error	Report generic failure and ask service owner to inspect logs

Final Response Pattern

After a successful publish/update, report:

Latest share URL.
Fixed version URL when available.
Version number.
Verification result from a real GET request.
Update token only when the user explicitly needs it; mark it as secret.

Do not claim success until the share URL has been verified with an HTTP GET returning status 200.

name	cf-sharepage
description	Use when a third-party agent needs to publish, update, or verify a single-file HTML page through an existing cf-sharepage API endpoint; use for API clients, share links, raw index.html uploads, bearer publish tokens, or bearer update tokens.

cf-sharepage API Client Skill

Overview

This skill is for API usage only. Do not use it for developing, deploying, or locally running the cf-sharepage service implementation.

Required Inputs

Before calling the API, identify:

baseUrl: the deployed service origin, for example https://share.example.com.
HTML input: a file path, generated HTML string, or raw HTML bytes.
For page creation: a publish bearer token.
For page updates: the existing update bearer token and either the update URL or both period and pageId.

Ask one focused question if any required input is missing.

Secret Handling

Treat publish tokens and update tokens as secrets.
Send tokens only in the Authorization: Bearer ... header.
Do not put tokens in URLs, logs, committed files, generated HTML, or browser storage.
Do not print returned update tokens in the final response unless the user needs them for future updates.
If returning an update token, label it clearly as secret.

API Contract

Create Page

POST /app
Authorization: Bearer <publishToken>
Content-Type: text/html

<!doctype html><html>...</html>

Expected success response:

{
  "pageId": "public-random-id",
  "period": "YYYYMM",
  "version": 0,
  "shareUrl": "https://.../s/YYYYMM/{pageId}",
  "updateToken": "secret-update-token"
}

Store period, pageId, shareUrl, and updateToken in the caller's approved secret/state location if future updates are needed.

Update Page

POST /app/YYYYMM/{pageId}/versions
Authorization: Bearer <updateToken>
Content-Type: text/html

<!doctype html><html>...</html>

Expected success response:

{
  "pageId": "public-random-id",
  "period": "YYYYMM",
  "version": 1,
  "shareUrl": "https://.../s/YYYYMM/{pageId}",
  "versionUrl": "https://.../s/YYYYMM/{pageId}/versions/1"
}

Read Published Pages

GET /s/YYYYMM/{pageId}
GET /s/YYYYMM/{pageId}/any/spa/path
GET /s/YYYYMM/{pageId}/versions/{version}
GET /s/YYYYMM/{pageId}/versions/{version}/any/spa/path

Latest URLs serve the current publish/index.html. Fixed-version URLs serve immutable historical index.html versions.

HTML Requirements

Send raw HTML bytes, not JSON, multipart form data, zip files, directories, or bundled asset folders.
Use Content-Type: text/html or text/html; charset=utf-8.
Body must be non-empty and start like an HTML document near the beginning, such as <!doctype html> or <html>.
V1 stores one index.html only. Inline assets or reference externally hosted assets if the page needs CSS, JS, images, or fonts.

Bash curl Client Pattern

Use environment variables for reusable values and secrets where possible.

BASE_URL: service origin, for example https://share.example.com.
PUBLISH_TOKEN: bearer token for creating pages.
UPDATE_TOKEN: bearer token returned by the create response for later updates.
PERIOD, PAGE_ID, and VERSION: values from API responses.

Create From A File

curl -X POST "$BASE_URL/app" \
  -H "Authorization: Bearer $PUBLISH_TOKEN" \
  -H "Content-Type: text/html" \
  --data-binary "@index.html"

Update From A File

curl -X POST "$BASE_URL/app/$PERIOD/$PAGE_ID/versions" \
  -H "Authorization: Bearer $UPDATE_TOKEN" \
  -H "Content-Type: text/html" \
  --data-binary "@index.html"

Verify Publication

curl -i "$BASE_URL/s/$PERIOD/$PAGE_ID"

curl -i "$BASE_URL/s/$PERIOD/$PAGE_ID/versions/$VERSION"

Response Handling

Status	Meaning	Client action
200	Share URL served successfully	Verify expected HTML content if needed
201	Create or update succeeded	Store returned metadata securely
400	Invalid HTML body or max versions reached	Check HTML shape or version cap
401	Missing or invalid bearer token	Re-check token source and header
404	Unknown route, page, or version	Check `period`, `pageId`, version, and route shape
413	HTML body exceeds service limit	Reduce size or ask service owner about limit changes
415	Unsupported content type	Send raw HTML with `Content-Type: text/html`
500	Unexpected service error	Report generic failure and ask service owner to inspect logs

Final Response Pattern

After a successful publish/update, report:

Latest share URL.
Fixed version URL when available.
Version number.
Verification result from a real GET request.
Update token only when the user explicitly needs it; mark it as secret.

Do not claim success until the share URL has been verified with an HTTP GET returning status 200.