From 6c7a67f4d6eb7389cd21eb232629517388f97994 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Fri, 10 Mar 2023 12:52:25 -0600 Subject: [PATCH] DEVDOCS-4719: [migrate] Upgrade docs to new Dev Center syntax and spec standards (#1212) Co-authored-by: Sarah Riehl Co-authored-by: Traci Porter Co-authored-by: Andrea Dao Co-authored-by: Tina Gomez Co-authored-by: Constanze Kratel Co-authored-by: Mark Murphy Co-authored-by: Katie Hoesley Co-authored-by: Stephen Hilliard Co-authored-by: Heather Barr Co-authored-by: Matthew Volk Co-authored-by: Nate Stewart --- .eslintrc.json | 10 + .github/workflows/lint.yml | 16 + .gitignore | 3 + .../{available-apis.md => available-apis.mdx} | 128 +- ...er-login-sso.md => customer-login-sso.mdx} | 31 +- ...ront-graphql.md => storefront-graphql.mdx} | 18 +- models/email_templates/_all.yml | 2064 +++++++++- .../email_templates/abandoned_cart_email.yml | 840 ++-- .../account_details_changed_email.yml | 219 +- .../account_reset_password_email.yml | 192 +- .../combined_order_status_email.yml | 448 ++- .../email_templates/create_account_email.yml | 217 +- .../create_guest_account_email.yml | 193 +- .../gift_certificate_email.yml | 264 +- models/email_templates/global.yml | 151 +- models/email_templates/invoice_email.yml | 890 +++-- .../order_message_notification.yml | 211 +- .../passwordless_login_email.yml | 206 +- .../email_templates/product_review_email.yml | 246 +- .../return_confirmation_email.yml | 281 +- .../return_status_change_email.yml | 347 +- models/webhooks/store_app_uninstalled.yml | 30 +- models/webhooks/store_cart_abandoned.yml | 32 +- models/webhooks/store_cart_converted.yml | 32 +- models/webhooks/store_cart_couponApplied.yml | 32 +- models/webhooks/store_cart_created.yml | 30 +- models/webhooks/store_cart_deleted.yml | 30 +- .../webhooks/store_cart_lineItem_created.yml | 32 +- .../webhooks/store_cart_lineItem_deleted.yml | 32 +- .../webhooks/store_cart_lineItem_updated.yml | 32 +- models/webhooks/store_cart_updated.yml | 30 +- models/webhooks/store_category_created.yml | 30 +- models/webhooks/store_category_deleted.yml | 30 +- models/webhooks/store_category_updated.yml | 30 +- .../store_customer_address_created.yml | 36 +- .../store_customer_address_deleted.yml | 36 +- .../store_customer_address_updated.yml | 36 +- models/webhooks/store_customer_created.yml | 30 +- models/webhooks/store_customer_deleted.yml | 30 +- ...mer_payment_instrument_default_updated.yml | 30 +- models/webhooks/store_customer_updated.yml | 30 +- models/webhooks/store_information_updated.yml | 28 +- models/webhooks/store_order_archived.yml | 30 +- models/webhooks/store_order_created.yml | 30 +- .../webhooks/store_order_message_created.yml | 36 +- .../webhooks/store_order_refund_created.yml | 36 +- models/webhooks/store_order_statusUpdated.yml | 40 +- models/webhooks/store_order_updated.yml | 30 +- models/webhooks/store_product_created.yml | 30 +- models/webhooks/store_product_deleted.yml | 30 +- .../store_product_inventory_order_updated.yml | 42 +- .../store_product_inventory_updated.yml | 42 +- models/webhooks/store_product_updated.yml | 30 +- models/webhooks/store_shipment_created.yml | 34 +- models/webhooks/store_shipment_deleted.yml | 34 +- models/webhooks/store_shipment_updated.yml | 34 +- models/webhooks/store_sku_created.yml | 40 +- models/webhooks/store_sku_deleted.yml | 40 +- .../store_sku_inventory_order_updated.yml | 46 +- .../webhooks/store_sku_inventory_updated.yml | 46 +- models/webhooks/store_sku_updated.yml | 40 +- models/webhooks/store_subscriber_created.yml | 30 +- models/webhooks/store_subscriber_deleted.yml | 30 +- models/webhooks/store_subscriber_updated.yml | 30 +- package-lock.json | 3371 +++++++++++++++++ package.json | 30 + reference/abandoned_cart_emails.v3.yaml | 106 +- reference/abandoned_carts.v3.yml | 156 +- reference/carts.sf.yml | 88 +- reference/carts.v3.yml | 293 +- reference/catalog.v3.yml | 3266 +++------------- reference/channels.v3.yml | 409 +- reference/checkouts.sf.yml | 39 +- reference/checkouts.v3.yml | 122 +- reference/consent.sf.yml | 18 +- reference/currencies.v2.yml | 274 +- reference/current_customer.yml | 24 +- reference/custom-template-associations.v3.yml | 144 +- reference/customer_login.yml | 24 +- reference/customers.sf.yml | 41 +- reference/customers.v2.yml | 665 +--- reference/customers.v3.yml | 199 +- reference/email_templates.v3.yml | 130 +- reference/form_fields.sf.yml | 18 +- reference/geography.v2.yml | 108 +- reference/global_refs.yaml | 56 +- reference/marketing.v2.yml | 537 +-- reference/orders.sf.yml | 19 +- reference/orders.v2.oas2.yml | 809 ++-- reference/orders.v3.yml | 374 +- reference/pages.v3.yml | 47 +- reference/payment_methods.v2.yml | 118 +- reference/payment_processing.yml | 214 +- reference/price_lists.v3.yml | 407 +- reference/pricing.sf.yml | 64 +- reference/redirects.v3.yml | 122 +- reference/scripts.v3.yml | 265 +- reference/settings.v3.yml | 371 +- reference/shipping.v2.yml | 1318 ++++--- reference/shipping.v3.yml | 88 +- reference/shipping_provider.yml | 37 +- reference/sites.v3.yml | 271 +- reference/store_content.v2.yml | 398 +- reference/store_information.v2.yml | 68 +- reference/store_logs.v3.yml | 53 +- reference/storefront_tokens.v3.yml | 149 +- reference/subscribers.v3.yml | 250 +- reference/subscriptions.sf.yml | 16 +- reference/tax.v3.yml | 124 +- reference/tax_classes.v2.yml | 140 +- reference/tax_properties.v3.yml | 167 +- reference/tax_provider.yml | 553 +-- reference/tax_rates_zones.v3.yml | 67 +- reference/tax_settings.v3.yml | 95 +- reference/themes.v3.yml | 370 +- reference/webhooks.v3.yml | 98 +- reference/widgets.v3.yml | 447 +-- reference/wishlists.v3.yml | 273 +- 118 files changed, 14051 insertions(+), 12272 deletions(-) create mode 100644 .eslintrc.json create mode 100644 .github/workflows/lint.yml rename docs/{available-apis.md => available-apis.mdx} (92%) rename docs/{customer-login-sso.md => customer-login-sso.mdx} (86%) rename docs/{storefront-graphql.md => storefront-graphql.mdx} (84%) create mode 100644 package-lock.json create mode 100644 package.json diff --git a/.eslintrc.json b/.eslintrc.json new file mode 100644 index 000000000..f7bcb7978 --- /dev/null +++ b/.eslintrc.json @@ -0,0 +1,10 @@ +{ + "extends": ["plugin:mdx/recommended"], + // optional, if you want to lint code blocks at the same time + "settings": { + "mdx/code-blocks": true, + // optional, if you want to disable language mapper, set it to `false` + // if you want to override the default language mapper inside, you can provide your own + "mdx/language-mapper": {} + } +} diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 000000000..7b9909307 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,16 @@ +name: lint-valid-mdx +on: + - pull_request + +jobs: + lint: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - name: Use Node.js v17.x + uses: actions/setup-node@v3 + with: + node-version: 17.x + - run: npm ci + - run: npm run lint diff --git a/.gitignore b/.gitignore index 485dee64b..f307f8393 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,4 @@ .idea +node_modules +.DS_Store + diff --git a/docs/available-apis.md b/docs/available-apis.mdx similarity index 92% rename from docs/available-apis.md rename to docs/available-apis.mdx index 49c9a1e3e..ba481d8bc 100644 --- a/docs/available-apis.md +++ b/docs/available-apis.mdx @@ -1,64 +1,64 @@ -# Available APIs - -## Storefront APIs - -### REST - -Manage a shopper's cart and checkout and fetch order data via client-side JavaScript on BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts. - -[Learn more about storefront APIs](/api-docs/storefront/overview). - -### GraphQL - -Use GraphQL to query data for headless storefronts and BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts. - -[Learn more about the GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview) - -### Add to cart URLs - -Append query string parameters to product and `/cart.php` URLs to pre-select a SKU or add a product to cart. Use these parameters to build custom add to cart links and forms on BigCommerce hosted storefronts and remote sites (such as WordPress, blog posts, and social media). - -[Learn more about add to cart URLs](/api-docs/cart-and-checkout/add-to-cart-url). - -### Current Customer - -Identify logged-in customers securely via JavaScript. - -[Learn more about the current customer API](/api-docs/customers/current-customer-api). - -### Customer Login SSO - -Enable single sign-on for shoppers on BigCommerce hosted storefronts. - -[Learn more about the customer login API](/api-docs/customers/customer-login-api). - -## Management APIs - -### V2 REST API - -Mananage store resources from server-side code. - -Some **V2** resources are not yet exposed in the **V3 API**; however, for resources that are accessible via both APIs, the **V3 API** is recommended; it contains performance optimizations and [other improvements](#v3-rest-api). - -### V3 REST API - -Mananage store resources from server-side code. - -Interactions with the **V3** API are very similar to that of the **V2** API; however, the **V3** API introduces a number of improvements: -* Most tasks can be performed with fewer API calls (for example, a product with variants and custom fields can be created in a single request) -* Each **V3** resource includes a `meta` object, simplifying pagination -* **V3** Brands, Categories, Products, and Product Variants expose a [metafields](/api-reference/catalog/catalog-api/product-metafields/createproductmetafield) resource for use by developers to store custom data. -* **V3** API is optimized for performance (in general, data can be sent, received, and processed faster via **V3**, relative to **V2**). - -[Learn more about the V3 API](/api-docs/getting-started/about-our-api). - -## Provider APIs - -Implement endpoints consumed by BigCommerce for custom integrations (ex: custom shipping carrier rates via `/rates`). - -[Learn more about the Shipping Provider API](/api-docs/store-management/shipping/shipping-provider-api). - -## Resources - -- [Deprecations and Sunsets](/api-docs/getting-started/deprecations-and-sunsets) -- [Difference between V2 and V3 Catalog REST APIs](/api-docs/store-management/catalog/v2-vs-v3) +# Available APIs + +## Storefront APIs + +### REST + +Manage a shopper's cart and checkout and fetch order data via client-side JavaScript on BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts. + +[Learn more about storefront APIs](/api-docs/storefront/overview). + +### GraphQL + +Use GraphQL to query data for headless storefronts and BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts. + +[Learn more about the GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview) + +### Add to cart URLs + +Append query string parameters to product and `/cart.php` URLs to pre-select a SKU or add a product to cart. Use these parameters to build custom add to cart links and forms on BigCommerce hosted storefronts and remote sites (such as WordPress, blog posts, and social media). + +[Learn more about add to cart URLs](/api-docs/cart-and-checkout/add-to-cart-url). + +### Current Customer + +Identify logged-in customers securely via JavaScript. + +[Learn more about the current customer API](/api-docs/customers/current-customer-api). + +### Customer Login SSO + +Enable single sign-on for shoppers on BigCommerce hosted storefronts. + +[Learn more about the customer login API](/api-docs/customers/customer-login-api). + +## Management APIs + +### V2 REST API + +Mananage store resources from server-side code. + +Some **V2** resources are not yet exposed in the **V3 API**; however, for resources that are accessible via both APIs, the **V3 API** is recommended; it contains performance optimizations and [other improvements](#v3-rest-api). + +### V3 REST API + +Mananage store resources from server-side code. + +Interactions with the **V3** API are very similar to that of the **V2** API; however, the **V3** API introduces a number of improvements: +* Most tasks can be performed with fewer API calls (for example, a product with variants and custom fields can be created in a single request) +* Each **V3** resource includes a `meta` object, simplifying pagination +* **V3** Brands, Categories, Products, and Product Variants expose a [metafields](/docs/rest-management/catalog/product-metafields#create-a-product-metafield) resource for use by developers to store custom data. +* **V3** API is optimized for performance (in general, data can be sent, received, and processed faster via **V3**, relative to **V2**). + +[Learn more about the V3 API](/api-docs/getting-started/about-our-api). + +## Provider APIs + +Implement endpoints consumed by BigCommerce for custom integrations (ex: custom shipping carrier rates via `/rates`). + +[Learn more about the Shipping Provider API](/api-docs/store-management/shipping/shipping-provider-api). + +## Resources + +- [Deprecations and Sunsets](/api-docs/getting-started/deprecations-and-sunsets) +- [Difference between V2 and V3 Catalog REST APIs](/api-docs/store-management/catalog/v2-vs-v3) diff --git a/docs/customer-login-sso.md b/docs/customer-login-sso.mdx similarity index 86% rename from docs/customer-login-sso.md rename to docs/customer-login-sso.mdx index 736c1e25b..9cad1bf37 100644 --- a/docs/customer-login-sso.md +++ b/docs/customer-login-sso.mdx @@ -1,12 +1,13 @@ # Customer Login SSO -* **Host**: {store_domain}/graphql +* **Host**: `{store_domain}/graphql` * **Protocols**:`https` * **Accepts**: `application/json` * **Responds With**: `application/json` -Download Spec: [customer_login.json](https://bigcommerce.stoplight.io/api/v1/projects/bigcommerce/api-reference/nodes/reference/customer_login.yml?branch=master&deref=all&format=json) +Download Spec: [customer_login.json](#) +{/* https://bigcommerce.stoplight.io/api/v1/projects/bigcommerce/api-reference/nodes/reference/customer_login.yml?branch=master&deref=all&format=json */} Create a login URL for customer single sign-on. @@ -14,7 +15,7 @@ Create a login URL for customer single sign-on. To log in a customer using the Customer Login API, redirect the customer's browser to the following access point URL: -```http +```http copy https://yourstore.example.com/login/token/{{TOKEN}} ``` @@ -35,7 +36,7 @@ We recommend writing a script to generate a login token since the `JWT iat` (iss ### JWT Header -```json +```json copy { "alg": "HS256", "typ": "JWT" @@ -50,7 +51,7 @@ We recommend writing a script to generate a login token since the `JWT iat` (iss To create the signature, sign the encoded header, the encoded payload, and client_secret using the `HMAC SHA256` algorithm. -```js +```js copy HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), @@ -63,21 +64,29 @@ To create the signature, sign the encoded header, the encoded payload, and clien Create `urlGenerator.js` node app and install dependencies. -```shell +```shell copy mkdir urlGenerator +``` +```shell copy cd urlGenerator +``` +```shell copy touch urlGenerator.js +``` +```shell copy npm init +``` +```shell copy npm install jsonwebtoken uuid ``` Paste the following into `urlGenerator/urlGenerator.js`. -```js +```js copy const jwt = require('jsonwebtoken'); const {v4: uuidv4} = require('uuid'); @@ -109,15 +118,15 @@ Paste the following into `urlGenerator/urlGenerator.js`. Replace `{{CLIENT_ID}}` and other variables with your credentials, then run the app. -```shell +```shell copy node urlGenerator.js ``` You should receive a complete access point URL as an output. - -> #### Note -> You are required to include the `channel_id` when using the login JWTs to redirect to an embedded checkout. Default value = 1. For more information, see the [Embedded Checkout Overview](/api-docs/storefronts/embedded-checkout/embedded-checkout-overview). + + You are required to include the `channel_id` when using the login JWTs to redirect to an embedded checkout. Default value = 1. For more information, see the [Embedded Checkout Overview](/api-docs/storefronts/embedded-checkout/embedded-checkout-overview). + ## Resources diff --git a/docs/storefront-graphql.md b/docs/storefront-graphql.mdx similarity index 84% rename from docs/storefront-graphql.md rename to docs/storefront-graphql.mdx index f59fbddf5..6ae0e3396 100644 --- a/docs/storefront-graphql.md +++ b/docs/storefront-graphql.mdx @@ -19,9 +19,9 @@ To explore Storefront nodes in an interactive graph, check out the [GraphQL Expl ### Request tokens with REST API -Create JWT tokens for authenticating cross-origin requests by making a `POST` request to the [Create a token](/api-reference/store-management/tokens/api-token/createtoken) endpoint. +Create JWT tokens for authenticating cross-origin requests by making a `POST` request to the [Create a token](/docs/storefront-auth/tokens#create-a-token) endpoint. -```http title="Example request: Create a token" lineNumbers +```http filename="Example request: Create a token" showLineNumbers copy POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json @@ -36,7 +36,7 @@ Accept: application/json } ```   -```json title="Example response: Create a token" lineNumbers +```json filename="Example response: Create a token" showLineNumbers copy { "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" @@ -47,7 +47,7 @@ Accept: application/json You can complete the GraphQL query call with any HTTP library. Use the `data.token` value from the preceding response as the `{{JWT}}` value in the `Authorization: Bearer {{JWT}}` header. -```http title="Example GraphQL query" lineNumbers +```http filename="Example GraphQL query" showLineNumbers copy POST /graphql Authorization: Bearer {{JWT}} Content-Type: application/json @@ -62,7 +62,7 @@ Content-Type: application/json Client scripts on BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil)-powered storefronts can access a token with the `{{settings.storefront_api.token}}` Handlebars object. -```handlebars title="Example GraphQL query script with Stencil token" lineNumbers +```handlebars filename="Example GraphQL query script with Stencil token" showLineNumbers copy