@mongoui/skills 0.1.8 → 0.2.0

package/skills/flink-flight-api/references/auth-and-credentials.md

@@ -1,136 +1,136 @@
-# Flink Auth And Credentials
-
-## Required Headers
-
-Send these headers on every Flink open-platform request:
-
-- `X-OP-App-Key`
-- `X-OP-Timestamp`
-- `X-OP-Nonce`
-- `X-OP-Sign`
-
-Optional headers that can help tracing or idempotency:
-
-- `X-OP-Client-Request-Id`
-- `X-Trace-Id`
-- `X-Idempotency-Key`
-
-`X-OP-App-Key` is the issued `open_app_id`.
-
-## Signature Algorithm
-
-Build the canonical string in this exact order, separated by newline characters:
-
-```text
-METHOD
-PATH
-CANONICAL_QUERY
-BODY_SHA256
-TIMESTAMP
-NONCE
-APP_KEY
-```
-
-Rules:
-
-- Uppercase `METHOD`.
-- Use the exact public request path, for example `/openapi/v1/flink/zh_CN/flight/search`.
-- Sort query parameters by key and then value before joining them as `k=v&k2=v2`.
-- Hash the raw request body bytes with SHA256 and use the lowercase hex digest.
-- Use the request timestamp exactly as sent in `X-OP-Timestamp`.
-- Use the request nonce exactly as sent in `X-OP-Nonce`.
-- Use the same `open_app_id` that is sent in `X-OP-App-Key`.
-- Sign the canonical string with the plain `open_app_secret` using HMAC-SHA256, then output lowercase hex.
-
-Notes:
-
-- Timestamp may be Unix seconds, Unix milliseconds, or RFC3339.
-- The platform validates timestamp drift within roughly `+-5` minutes.
-- Nonce must be unique for the same app key in a short time window.
-- For empty bodies, hash the empty byte string.
-
-Use `scripts/flink_signed_request.py` when the task needs a deterministic implementation or a quick smoke test.
-
-## Credential Acquisition
-
-Treat credentials as environment-specific.
-
-Sandbox:
-
-1. The developer applies for app access.
-2. The operator activates the app access with `env_type=sandbox`.
-3. The platform records sandbox Flink mapping and issues a sandbox `open_app_id/open_app_secret`.
-4. The app access becomes `sandbox_active`.
-
-Production:
-
-1. The developer submits production access after sandbox work is complete.
-2. The operator approves production with `env_type=production`.
-3. The platform issues a production `open_app_id/open_app_secret`.
-4. The production credential becomes usable only after the app access reaches `production_active`.
-
-Important constraints:
-
-- Sandbox and production credentials are separate and not interchangeable.
-- Developers can see platform credentials only.
-- Developers cannot see Flink downstream secrets.
-
-## How To View Or Reset Keys
-
-Developer portal APIs:
-
-- `GET /api/portal/apps/{app_id}/credentials`
-  - Returns the credential list for the app.
-  - Includes `open_app_id`, `provider_code`, `env_type`, `open_secret_version`, and masked secret data.
-  - Does not return the plain secret in normal list queries.
-- `POST /api/portal/apps/{app_id}/credentials/reset`
-  - Resets the platform secret and returns `plain_open_secret`.
-  - If the app has more than one credential mapping, pass both `provider_code` and `env_type`.
-
-Response fields that matter:
-
-- `open_app_id`: the App Key to place into `X-OP-App-Key`
-- `open_secret_masked`: masked secret for display only
-- `open_secret_version`: useful for rotation tracking
-- `plain_open_secret`: returned only on first issuance or reset
-
-Practical guidance:
-
-- If a developer says "I can only see a masked secret", instruct them to use the reset endpoint or the corresponding portal UI action.
-- If the task is only to call sandbox APIs, do not assume production credentials work.
-- If the app has both sandbox and production mappings, always name the target `env_type` explicitly.
-
-## Common Auth Failures
-
-- `APP_KEY_INVALID`
-  - Wrong `open_app_id`, wrong environment, or the credential does not exist.
-- `SIGN_ERROR`
-  - Wrong secret, wrong path, wrong query ordering, wrong body hash, or newline formatting mismatch.
-- `TIMESTAMP_EXPIRED`
-  - Clock skew exceeds the allowed window.
-- `NONCE_REPLAY`
-  - Nonce was reused under the same app key.
-- `PRODUCT_FORBIDDEN`
-  - The app is not enabled for the product, the mapping is not active, or an IP whitelist rule failed.
-
-## Response Contract
-
-The platform wraps business responses in a common envelope:
-
-```json
-{
-  "request_id": "req_xxx",
-  "trace_id": "trc_xxx",
-  "downstream_request_id": "optional",
-  "code": "SUCCESS",
-  "message": "ok",
-  "data": {}
-}
-```
-
-Interpretation:
-
-- `request_id` and `trace_id` are platform-side tracing keys.
-- `downstream_request_id` is the Flink request identifier when available.
-- `code=SUCCESS` means the business call succeeded.
-- `code=SUPPLIER_BIZ_ERROR` means Flink returned a business error and can still arrive with HTTP `200`.
+# Flink Auth And Credentials
+
+## Required Headers
+
+Send these headers on every Flink open-platform request:
+
+- `X-OP-App-Key`
+- `X-OP-Timestamp`
+- `X-OP-Nonce`
+- `X-OP-Sign`
+
+Optional headers that can help tracing or idempotency:
+
+- `X-OP-Client-Request-Id`
+- `X-Trace-Id`
+- `X-Idempotency-Key`
+
+`X-OP-App-Key` is the issued `open_app_id`.
+
+## Signature Algorithm
+
+Build the canonical string in this exact order, separated by newline characters:
+
+```text
+METHOD
+PATH
+CANONICAL_QUERY
+BODY_SHA256
+TIMESTAMP
+NONCE
+APP_KEY
+```
+
+Rules:
+
+- Uppercase `METHOD`.
+- Use the exact public request path, for example `/openapi/v1/flink/zh_CN/flight/search`.
+- Sort query parameters by key and then value before joining them as `k=v&k2=v2`.
+- Hash the raw request body bytes with SHA256 and use the lowercase hex digest.
+- Use the request timestamp exactly as sent in `X-OP-Timestamp`.
+- Use the request nonce exactly as sent in `X-OP-Nonce`.
+- Use the same `open_app_id` that is sent in `X-OP-App-Key`.
+- Sign the canonical string with the plain `open_app_secret` using HMAC-SHA256, then output lowercase hex.
+
+Notes:
+
+- Timestamp may be Unix seconds, Unix milliseconds, or RFC3339.
+- The platform validates timestamp drift within roughly `+-5` minutes.
+- Nonce must be unique for the same app key in a short time window.
+- For empty bodies, hash the empty byte string.
+
+Use `scripts/flink_signed_request.py` when the task needs a deterministic implementation or a quick smoke test.
+
+## Credential Acquisition
+
+Treat credentials as environment-specific.
+
+Sandbox:
+
+1. The developer applies for app access.
+2. The operator activates the app access with `env_type=sandbox`.
+3. The platform records sandbox Flink mapping and issues a sandbox `open_app_id/open_app_secret`.
+4. The app access becomes `sandbox_active`.
+
+Production:
+
+1. The developer submits production access after sandbox work is complete.
+2. The operator approves production with `env_type=production`.
+3. The platform issues a production `open_app_id/open_app_secret`.
+4. The production credential becomes usable only after the app access reaches `production_active`.
+
+Important constraints:
+
+- Sandbox and production credentials are separate and not interchangeable.
+- Developers can see platform credentials only.
+- Developers cannot see Flink downstream secrets.
+
+## How To View Or Reset Keys
+
+Developer portal APIs:
+
+- `GET /api/portal/apps/{app_id}/credentials`
+  - Returns the credential list for the app.
+  - Includes `open_app_id`, `provider_code`, `env_type`, `open_secret_version`, and masked secret data.
+  - Does not return the plain secret in normal list queries.
+- `POST /api/portal/apps/{app_id}/credentials/reset`
+  - Resets the platform secret and returns `plain_open_secret`.
+  - If the app has more than one credential mapping, pass both `provider_code` and `env_type`.
+
+Response fields that matter:
+
+- `open_app_id`: the App Key to place into `X-OP-App-Key`
+- `open_secret_masked`: masked secret for display only
+- `open_secret_version`: useful for rotation tracking
+- `plain_open_secret`: returned only on first issuance or reset
+
+Practical guidance:
+
+- If a developer says "I can only see a masked secret", instruct them to use the reset endpoint or the corresponding portal UI action.
+- If the task is only to call sandbox APIs, do not assume production credentials work.
+- If the app has both sandbox and production mappings, always name the target `env_type` explicitly.
+
+## Common Auth Failures
+
+- `APP_KEY_INVALID`
+  - Wrong `open_app_id`, wrong environment, or the credential does not exist.
+- `SIGN_ERROR`
+  - Wrong secret, wrong path, wrong query ordering, wrong body hash, or newline formatting mismatch.
+- `TIMESTAMP_EXPIRED`
+  - Clock skew exceeds the allowed window.
+- `NONCE_REPLAY`
+  - Nonce was reused under the same app key.
+- `PRODUCT_FORBIDDEN`
+  - The app is not enabled for the product, the mapping is not active, or an IP whitelist rule failed.
+
+## Response Contract
+
+The platform wraps business responses in a common envelope:
+
+```json
+{
+  "request_id": "req_xxx",
+  "trace_id": "trc_xxx",
+  "downstream_request_id": "optional",
+  "code": "SUCCESS",
+  "message": "ok",
+  "data": {}
+}
+```
+
+Interpretation:
+
+- `request_id` and `trace_id` are platform-side tracing keys.
+- `downstream_request_id` is the Flink request identifier when available.
+- `code=SUCCESS` means the business call succeeded.
+- `code=SUPPLIER_BIZ_ERROR` means Flink returned a business error and can still arrive with HTTP `200`.

package/skills/flink-flight-api/references/endpoint-index.md

@@ -1,92 +1,92 @@
-# Flink Endpoint Index
-
-All routes are public gateway routes. Sign the public path, not the downstream Flink path.
-
-## Flight Search
-
-- `flink.flight.search`
-  - `POST /openapi/v1/flink/{lang}/flight/search`
-  - Required body fields: `cabinClass`, `tripType`, `journeys`, `adultNum`
-  - Common optional fields: `childNum`, `infantNum`, `airline`, `transferNumber`, `journeyId`, `corporate`
-  - Main output to preserve: `priceKey`
-- `flink.flight.cabin`
-  - `POST /openapi/v1/flink/{lang}/flight/cabin`
-  - Required body fields: `priceKey`
-  - Use to expand or refine fare options for a selected result
-- `flink.flight.verify`
-  - `POST /openapi/v1/flink/{lang}/flight/verify`
-  - Required body fields: `priceKey`
-  - Use before order creation
-
-## Order Management
-
-- `flink.flight.order.create`
-  - `POST /openapi/v1/flink/{lang}/flight/order/create`
-  - Required body fields: `priceKey`, `contactName`, `contactRegion`, `contactPhone`, `contactEmail`, `passenger`
-  - Use after verify or directly after search or cabin when allowed by the business flow
-- `flink.flight.order.pay`
-  - `POST /openapi/v1/flink/{lang}/flight/order/pay`
-  - Required body fields: `orderNo`, `amount`, `type`
-  - `type=0` for standard order, `type=1` for change order
-- `flink.flight.order.detail`
-  - `POST /openapi/v1/flink/{lang}/flight/order/detail`
-  - Required body fields: `orderNo`
-- `flink.flight.order.cancel`
-  - `POST /openapi/v1/flink/{lang}/flight/order/cancel`
-  - Required body fields: `orderNo`
-
-## Change
-
-- `flink.flight.change.search`
-  - `POST /openapi/v1/flink/{lang}/flight/change/search`
-  - Required body fields: `orderNo`, `cabinClass`, `date`, `passenger`, `segmentId`
-- `flink.flight.change.apply`
-  - `POST /openapi/v1/flink/{lang}/flight/change/apply`
-  - Required body fields: `orderNo`, `passenger`, `segmentId`, `priceKey`, `changeOrderType`, `changeType`, `contactName`, `contactPhone`, `contactEmail`, `changeReasonType`, `changeReason`
-  - `fileList` is required by schema when attachments are involved in involuntary changes
-- `flink.flight.change.cancel`
-  - `POST /openapi/v1/flink/{lang}/flight/change/cancel`
-  - Required body fields: `changeOrderNo`
-- `flink.flight.change.detail`
-  - `POST /openapi/v1/flink/{lang}/flight/change/detail`
-  - Required body fields: `changeOrderNo`
-
-## Refund
-
-- `flink.flight.refund.apply`
-  - `POST /openapi/v1/flink/{lang}/flight/refund/apply`
-  - Required body fields: `orderNo`, `orderType`, `passenger`, `segmentId`, `refundType`, `reasonType`, `reason`, `fileList`, `contactName`, `contactRegion`, `contactPhone`, `contactEmail`
-- `flink.flight.refund.detail`
-  - `POST /openapi/v1/flink/{lang}/flight/refund/detail`
-  - Required body fields: `refundOrderNo`
-- `flink.flight.refund.confirm`
-  - `POST /openapi/v1/flink/{lang}/flight/refund/confirm`
-  - Required body fields: `refundOrderNo`, `confirm`
-
-## Basic Data
-
-- `flink.airports.list`
-  - `POST /openapi/v1/flink/{lang}/airports/list`
-  - Required body fields: `page`, `pageSize`
-  - Common optional fields: `keyword`
-- `flink.airlines.list`
-  - `POST /openapi/v1/flink/{lang}/airlines/list`
-  - Required body fields: `page`, `pageSize`
-  - Common optional fields: `keyword`, `code`
-- `flink.airports.search`
-  - `POST /openapi/v1/flink/{lang}/airports/search`
-  - Common body field: `keyword`
-- `flink.nationality.list`
-  - `POST /openapi/v1/flink/{lang}/nationality/list`
-  - No required body fields in the current schema
-- `flink.fields`
-  - `GET /openapi/v1/flink/fields`
-  - Query parameters: `priceKey` optional, `orderNo` optional
-  - Send at least one of `priceKey` or `orderNo`
-
-## Global Notes
-
-- `{lang}` is required on every route except `flink.fields`.
-- Platform error responses can return `401`, `403`, `404`, `500`, `502`, or `504`.
-- Common auth-related `401` codes are `APP_KEY_INVALID`, `SIGN_ERROR`, `TIMESTAMP_EXPIRED`, and `NONCE_REPLAY`.
-- Common `403` cause is `PRODUCT_FORBIDDEN`.
+# Flink Endpoint Index
+
+All routes are public gateway routes. Sign the public path, not the downstream Flink path.
+
+## Flight Search
+
+- `flink.flight.search`
+  - `POST /openapi/v1/flink/{lang}/flight/search`
+  - Required body fields: `cabinClass`, `tripType`, `journeys`, `adultNum`
+  - Common optional fields: `childNum`, `infantNum`, `airline`, `transferNumber`, `journeyId`, `corporate`
+  - Main output to preserve: `priceKey`
+- `flink.flight.cabin`
+  - `POST /openapi/v1/flink/{lang}/flight/cabin`
+  - Required body fields: `priceKey`
+  - Use to expand or refine fare options for a selected result
+- `flink.flight.verify`
+  - `POST /openapi/v1/flink/{lang}/flight/verify`
+  - Required body fields: `priceKey`
+  - Use before order creation
+
+## Order Management
+
+- `flink.flight.order.create`
+  - `POST /openapi/v1/flink/{lang}/flight/order/create`
+  - Required body fields: `priceKey`, `contactName`, `contactRegion`, `contactPhone`, `contactEmail`, `passenger`
+  - Use after verify or directly after search or cabin when allowed by the business flow
+- `flink.flight.order.pay`
+  - `POST /openapi/v1/flink/{lang}/flight/order/pay`
+  - Required body fields: `orderNo`, `amount`, `type`
+  - `type=0` for standard order, `type=1` for change order
+- `flink.flight.order.detail`
+  - `POST /openapi/v1/flink/{lang}/flight/order/detail`
+  - Required body fields: `orderNo`
+- `flink.flight.order.cancel`
+  - `POST /openapi/v1/flink/{lang}/flight/order/cancel`
+  - Required body fields: `orderNo`
+
+## Change
+
+- `flink.flight.change.search`
+  - `POST /openapi/v1/flink/{lang}/flight/change/search`
+  - Required body fields: `orderNo`, `cabinClass`, `date`, `passenger`, `segmentId`
+- `flink.flight.change.apply`
+  - `POST /openapi/v1/flink/{lang}/flight/change/apply`
+  - Required body fields: `orderNo`, `passenger`, `segmentId`, `priceKey`, `changeOrderType`, `changeType`, `contactName`, `contactPhone`, `contactEmail`, `changeReasonType`, `changeReason`
+  - `fileList` is required by schema when attachments are involved in involuntary changes
+- `flink.flight.change.cancel`
+  - `POST /openapi/v1/flink/{lang}/flight/change/cancel`
+  - Required body fields: `changeOrderNo`
+- `flink.flight.change.detail`
+  - `POST /openapi/v1/flink/{lang}/flight/change/detail`
+  - Required body fields: `changeOrderNo`
+
+## Refund
+
+- `flink.flight.refund.apply`
+  - `POST /openapi/v1/flink/{lang}/flight/refund/apply`
+  - Required body fields: `orderNo`, `orderType`, `passenger`, `segmentId`, `refundType`, `reasonType`, `reason`, `fileList`, `contactName`, `contactRegion`, `contactPhone`, `contactEmail`
+- `flink.flight.refund.detail`
+  - `POST /openapi/v1/flink/{lang}/flight/refund/detail`
+  - Required body fields: `refundOrderNo`
+- `flink.flight.refund.confirm`
+  - `POST /openapi/v1/flink/{lang}/flight/refund/confirm`
+  - Required body fields: `refundOrderNo`, `confirm`
+
+## Basic Data
+
+- `flink.airports.list`
+  - `POST /openapi/v1/flink/{lang}/airports/list`
+  - Required body fields: `page`, `pageSize`
+  - Common optional fields: `keyword`
+- `flink.airlines.list`
+  - `POST /openapi/v1/flink/{lang}/airlines/list`
+  - Required body fields: `page`, `pageSize`
+  - Common optional fields: `keyword`, `code`
+- `flink.airports.search`
+  - `POST /openapi/v1/flink/{lang}/airports/search`
+  - Common body field: `keyword`
+- `flink.nationality.list`
+  - `POST /openapi/v1/flink/{lang}/nationality/list`
+  - No required body fields in the current schema
+- `flink.fields`
+  - `GET /openapi/v1/flink/fields`
+  - Query parameters: `priceKey` optional, `orderNo` optional
+  - Send at least one of `priceKey` or `orderNo`
+
+## Global Notes
+
+- `{lang}` is required on every route except `flink.fields`.
+- Platform error responses can return `401`, `403`, `404`, `500`, `502`, or `504`.
+- Common auth-related `401` codes are `APP_KEY_INVALID`, `SIGN_ERROR`, `TIMESTAMP_EXPIRED`, and `NONCE_REPLAY`.
+- Common `403` cause is `PRODUCT_FORBIDDEN`.