From 9406d78815c60b80cefe9a233fcca4d0311302be Mon Sep 17 00:00:00 2001 From: Kenneth Kalmer Date: Wed, 26 Nov 2025 21:54:39 +0000 Subject: [PATCH 1/6] Remove textile and ERB processing code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove all code that processes textile files and ERB templates from the build pipeline. Textile content files remain in the repository but are no longer parsed or rendered. Changes: - Remove textile-js imports and usage from createPages and onCreateNode - Remove ERB processing from pre-parser pipeline - Remove textile-partials handling from transform utilities - Update parser steps to remove ERB and textile workarounds After this commit, the build generates 241 MDX pages with no textile processing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../parser-steps/html-parser.ts | 46 ---- .../parser-steps/post-parser.ts | 26 --- .../parser-steps/pre-parser.ts | 63 ----- data/createPages/index.ts | 218 +----------------- data/onCreateNode/index.ts | 29 --- data/transform/index.js | 13 +- data/transform/parser-enhancements/index.js | 2 +- data/transform/pre-parser/index.ts | 17 +- 8 files changed, 5 insertions(+), 409 deletions(-) delete mode 100644 data/cli-functionality/parser-steps/html-parser.ts delete mode 100644 data/cli-functionality/parser-steps/post-parser.ts delete mode 100644 data/cli-functionality/parser-steps/pre-parser.ts diff --git a/data/cli-functionality/parser-steps/html-parser.ts b/data/cli-functionality/parser-steps/html-parser.ts deleted file mode 100644 index c3583aa386..0000000000 --- a/data/cli-functionality/parser-steps/html-parser.ts +++ /dev/null @@ -1,46 +0,0 @@ -import cheerio from 'cheerio'; -import { addAPIKeyInfoToCodeBlock } from '../../../data/html-parser/add-info-to-codeblocks/codeblock-api-key-info'; -import { addRandomChannelInfoToCodeBlock } from '../../../data/html-parser/add-info-to-codeblocks/codeblock-random-channel-name'; -import { removeChildrenFromPreWrappedCodeElements } from '../../../data/html-parser/remove-children-from-pre-wrapped-code-elements'; -import { removeParagraphsFromDefinitionListsAndMerge } from '../../../data/html-parser/remove-paragraphs-from-definition-lists'; -import { duplicateLangAttributes } from '../../../data/html-parser/duplicate-lang-attributes'; -import { liftLangAttributes } from '../../../data/html-parser/lift-lang-attributes'; -import { Step } from './pre-parser'; - -const loadParseAndReturnWith = (fn: (nodes: cheerio.Selector) => cheerio.Cheerio | void) => (content: string) => { - const loadedDom = cheerio.load(content); - fn(loadedDom); - return loadedDom.html(); -}; - -export const htmlParserSteps: Step[] = [ - { - fn: loadParseAndReturnWith(liftLangAttributes), - description: - 'Promotes
elements inside a
element so that it wraps the entire
"row" of a
', - }, - { - fn: loadParseAndReturnWith(duplicateLangAttributes), - description: - 'Captures any multiple language attributes that were previously missed and duplicates them, e.g. lang="javascript,nodejs"', - }, - { - fn: loadParseAndReturnWith(addAPIKeyInfoToCodeBlock), - description: - 'Adds API key info to the code element attributes, so that the React component knows to look for the API key', - }, - { - fn: loadParseAndReturnWith(addRandomChannelInfoToCodeBlock), - description: - 'Adds Random Channel info to code element attributes, so that the React component knows if it should look for the channel info', - }, - { - fn: loadParseAndReturnWith(removeParagraphsFromDefinitionListsAndMerge), - description: - 'Remove empty paragraphs from definition lists, then merge consecutive definition lists together into one list', - }, - { - fn: loadParseAndReturnWith(removeChildrenFromPreWrappedCodeElements), - description: 'Try to get rid of child elements that should not exist in code elements wrapped in 
 tags',
-  },
-];
diff --git a/data/cli-functionality/parser-steps/post-parser.ts b/data/cli-functionality/parser-steps/post-parser.ts
deleted file mode 100644
index aa11333afc..0000000000
--- a/data/cli-functionality/parser-steps/post-parser.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { rootLevelTextWrapper } from '../../../data/transform/post-parser/root-level-text-wrapper';
-import { addGithubLineBreaks, convertExternalLinksToBlankTarget } from '../../../data/transform/post-parser';
-import { convertBlangBlocksToHtml } from '../../../data/transform/post-parser/blang';
-import { Step } from './pre-parser';
-
-export const postParserSteps: Step[] = [
-  {
-    fn: convertExternalLinksToBlankTarget,
-    description: 'Detects links to non-Ably destintations and adds a rel blank',
-  },
-  {
-    fn: convertBlangBlocksToHtml,
-    description:
-      'A blang block is defined as blang[language]. followed by some indented lines. It is encoded as a set of tokens that are ultimately rendered as divs, in an attempt to survive the textile process. This is the point where we hydrate the div from the blang tokens.',
-  },
-  {
-    fn: addGithubLineBreaks,
-    description:
-      'Adds line breaks for github-style code blocks back in, after they were turned into tokens in the pre-parser stage',
-  },
-  {
-    fn: rootLevelTextWrapper,
-    description:
-      'Wraps any root level elements that are not wrapped in a paragraph tag, to avoid text nodes being missed by the Cheerio loaded in the next, html-parser stage',
-  },
-];
diff --git a/data/cli-functionality/parser-steps/pre-parser.ts b/data/cli-functionality/parser-steps/pre-parser.ts
deleted file mode 100644
index 9ce7b5f28c..0000000000
--- a/data/cli-functionality/parser-steps/pre-parser.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-import { removeExternalClassFromLinks } from '../../transform/pre-parser/remove-external-class-from-links';
-import { replaceERB } from '../../transform/pre-parser/erbjs';
-import { addMinimizedIndent, addMinimizeForHeadings, stripComments } from '../../transform/pre-parser/semantic';
-import { removeNewlinesBeforeClosingTags, recursivelyProcessDivs } from '../../transform/pre-parser';
-import {
-  addLanguageSupportForBlockQuotes,
-  addLanguageSupportForGithubStyleCode,
-  addLanguageSupportForHeadings,
-  convertBlangBlocksToTokens,
-  convertJSAllToNodeAndJavaScript,
-  duplicateLanguageBlocks,
-  enforceWhiteSpaceLevelsBetweenLanguageElements,
-} from '../../transform/pre-parser/language';
-
-export type Step = { fn: StringTransformation; description?: string };
-export const preParserSteps: Step[] = [
-  {
-    fn: removeExternalClassFromLinks,
-  },
-  {
-    fn: replaceERB,
-    description: `Replaces Ruby templating code`,
-  },
-  {
-    fn: stripComments,
-  },
-  {
-    fn: removeNewlinesBeforeClosingTags,
-  },
-  {
-    fn: addMinimizeForHeadings,
-  },
-  {
-    fn: addMinimizedIndent,
-  },
-  {
-    fn: convertJSAllToNodeAndJavaScript,
-    description: `Expands language tags containing 'jsall' so they contain 'nodejs, javascript'`,
-  },
-  {
-    fn: convertBlangBlocksToTokens,
-    description: `Blang blocks are defined by blang[]. sections introducing, then any number of indented lines`,
-  },
-  {
-    fn: addLanguageSupportForGithubStyleCode,
-  },
-  {
-    fn: duplicateLanguageBlocks,
-  },
-  {
-    fn: enforceWhiteSpaceLevelsBetweenLanguageElements,
-  },
-  {
-    fn: addLanguageSupportForBlockQuotes,
-  },
-  {
-    fn: addLanguageSupportForHeadings,
-  },
-  {
-    fn: recursivelyProcessDivs,
-    description: `Divs across multiple lines pose an issue for textile-js.\nWe detect these divs and process the internal textile separately, marking it as 'notextile' in the process.`,
-  },
-];
diff --git a/data/createPages/index.ts b/data/createPages/index.ts
index 4b96204cb0..99d7507122 100644
--- a/data/createPages/index.ts
+++ b/data/createPages/index.ts
@@ -1,77 +1,12 @@
 import path from 'path';
-import textile from 'textile-js';
-import { identity } from 'lodash';
-import { safeFileExists } from './safeFileExists';
-import { flattenContentOrderedList, maybeRetrievePartial } from '../transform';
-import { postParser } from '../transform/post-parser';
-import { htmlParser } from '../html-parser';
-import { createLanguagePageVariants } from './createPageVariants';
-import { LATEST_ABLY_API_VERSION_STRING } from '../transform/constants';
-import { createContentMenuDataFromPage } from './createContentMenuDataFromPage';
-import { DEFAULT_LANGUAGE } from './constants';
 import { writeRedirectToConfigFile, getRedirectCount } from './writeRedirectToConfigFile';
 import { siteMetadata } from '../../gatsby-config';
-import { GatsbyNode, Reporter } from 'gatsby';
+import { GatsbyNode } from 'gatsby';
 import { examples, DEFAULT_EXAMPLE_LANGUAGES } from '../../src/data/examples/';
 import { Example } from '../../src/data/examples/types';
 
-const documentTemplate = path.resolve(`src/templates/document.tsx`);
-const apiReferenceTemplate = path.resolve(`src/templates/apiReference.tsx`);
 const examplesTemplate = path.resolve(`src/templates/examples.tsx`);
 
-interface Edge {
-  node: {
-    slug: string;
-    version?: string;
-    contentOrderedList: Array<{
-      data: string;
-      type: string;
-    }>;
-    meta?: {
-      redirect_from?: string[];
-    };
-  };
-}
-
-interface DocumentQueryResult {
-  allError: {
-    nodes: {
-      message: string;
-    }[];
-  };
-  allFileHtml: {
-    edges: {
-      node: {
-        slug: string;
-        contentOrderedList: {
-          data: string;
-          type: string;
-        }[];
-        meta: {
-          redirect_from?: string[];
-        };
-      };
-    }[];
-  };
-}
-
-interface ApiReferenceQueryResult {
-  allFileHtml: {
-    edges: {
-      node: {
-        slug: string;
-        contentOrderedList: {
-          data: string;
-          type: string;
-        }[];
-        meta: {
-          redirect_from?: string[];
-        };
-      };
-    }[];
-  };
-}
-
 interface ExampleQueryResult {
   allExampleFile: {
     nodes: {
@@ -105,85 +40,8 @@ export const createPages: GatsbyNode['createPages'] = async ({
   actions: { createPage, createRedirect },
   reporter,
 }) => {
-  /**
-   * It's not ideal to have:
-   * * the reusable function `documentCreator` defined inline like this
-   * * so much of `documentCreator` being imperative processing of data
-   * - but Gatsby throws horrible unrelated errors (from onCreateNode) if
-   * you try to extract any of this functionality into an independent composable
-   * and testable function.
-   */
-
   // Initialize redirect writer with reporter
   const writeRedirect = writeRedirectToConfigFile('config/nginx-redirects.conf', reporter);
-
-  // DOCUMENT TEMPLATE
-  const documentResult = await graphql(`
-    query {
-      allError {
-        nodes {
-          message
-        }
-      }
-      allFileHtml(filter: { articleType: { eq: "document" } }) {
-        edges {
-          node {
-            slug
-            contentOrderedList {
-              data
-              type
-            }
-            meta {
-              redirect_from
-            }
-          }
-        }
-      }
-    }
-  `);
-
-  /**
-   * We could log here, the reason we don't right now is that the error should already have been caught and logged.
-   * Because Gatsby spawns a bunch of async processes during the onCreateNode step, though, and errors don't prevent
-   * the onCreateNode processes from continuing, the workaround is to create Error nodes and then quit when we get
-   * to the next synchronous stage in the Gatsby pipeline if any Error nodes exist.
-   * It's an awkward solution and an alternative would be welcome, I'm not sure what we would do instead though.
-   * We could log only during createPages and never during onCreateNode, but then if there's an error that does manage
-   * to crash Gatsby somehow or the Error Node is broken, we wouldn't see the output.
-   *
-   * For context:
-   * The original ticket here was EDX-21. When I originally detected missing meta descriptions, I wanted to
-   * console.warn and continue just so editors could see the error. However it was decided that it should be a
-   * requirement to always have a meta description, so the app had to avoid building while still throwing & logging
-   * an error when a page didn't have a meta description.
-   */
-  if (documentResult.data?.allError.nodes && documentResult.data.allError.nodes.length > 0) {
-    process.exit(1);
-  }
-
-  // API REFERENCES TEMPLATE
-  const apiReferenceResult = await graphql(`
-    query {
-      allFileHtml(filter: { articleType: { eq: "apiReference" } }) {
-        edges {
-          node {
-            slug
-            contentOrderedList {
-              data
-              type
-            }
-            meta {
-              redirect_from
-            }
-          }
-        }
-      }
-    }
-  `);
-
-  // Query partials used in textile files
-  const retrievePartialFromGraphQL = maybeRetrievePartial(graphql);
-
   // Query our examples
   const examplesResult = await graphql(`
     query {
@@ -218,70 +76,6 @@ export const createPages: GatsbyNode['createPages'] = async ({
     }
   `);
 
-  const documentCreator =
-    (documentTemplate: string) =>
-    async (edge: Edge): Promise => {
-      const content = flattenContentOrderedList(
-        await Promise.all(edge.node.contentOrderedList.map(retrievePartialFromGraphQL)),
-      )
-        .map((content: { data: unknown }) => (content.data ? content.data : ''))
-        .join('\n');
-
-      const postParsedContent = postParser(textile(content));
-      const contentOrderedList = htmlParser(postParsedContent);
-      const contentMenu = contentOrderedList.map((item) => createContentMenuDataFromPage(item));
-      const [languages, contentMenuObject] = createLanguagePageVariants(identity, documentTemplate)(
-        contentOrderedList,
-        edge.node.slug,
-      );
-
-      contentMenuObject[DEFAULT_LANGUAGE] = contentMenu;
-
-      const slug = edge.node.slug;
-      const script = safeFileExists(`static/scripts/${slug}.js`);
-      const pagePath = `/docs/${slug}`;
-
-      const redirectFromList = edge.node.meta?.redirect_from;
-
-      if (redirectFromList) {
-        redirectFromList.forEach((redirectFrom) => {
-          const redirectFromUrl = new URL(redirectFrom, siteMetadata.siteUrl);
-
-          if (!redirectFromUrl.hash) {
-            // We need to be prefix aware just like Gatsby's internals so it works
-            // with nginx redirects
-            writeRedirect(redirectFrom, pagePath);
-          } else {
-            reporter.info(`[REDIRECTS] Skipping hash fragment redirect: ${redirectFrom} (hash: ${redirectFromUrl.hash})`);
-          }
-
-          createRedirect({
-            fromPath: redirectFrom,
-            toPath: pagePath,
-            isPermanent: true,
-            force: true,
-            redirectInBrowser: true,
-          });
-        });
-      }
-
-      createPage({
-        path: pagePath,
-        component: documentTemplate,
-        context: {
-          slug,
-          version: edge.node.version ?? LATEST_ABLY_API_VERSION_STRING,
-          language: DEFAULT_LANGUAGE,
-          languages,
-          contentOrderedList,
-          contentMenu: contentMenuObject,
-          script,
-          layout: { leftSidebar: true, rightSidebar: true, searchBar: true, template: 'base' },
-        },
-      });
-      return slug;
-    };
-
   createRedirect({
     fromPath: '/',
     toPath: '/docs',
@@ -289,14 +83,6 @@ export const createPages: GatsbyNode['createPages'] = async ({
     redirectInBrowser: true,
   });
 
-  if (!documentResult.data) {
-    throw new Error('Document result is undefined');
-  }
-
-  if (!apiReferenceResult.data) {
-    throw new Error('API reference result is undefined');
-  }
-
   if (!mdxRedirectsResult.data) {
     throw new Error('MDX redirects result is undefined');
   }
@@ -365,8 +151,6 @@ export const createPages: GatsbyNode['createPages'] = async ({
   };
 
   await Promise.all([
-    ...documentResult.data.allFileHtml.edges.map(documentCreator(documentTemplate)),
-    ...apiReferenceResult.data.allFileHtml.edges.map(documentCreator(apiReferenceTemplate)),
     ...examples.map(exampleCreator),
     ...mdxRedirectsResult.data.allMdx.nodes.map(mdxRedirectCreator),
   ]);
diff --git a/data/onCreateNode/index.ts b/data/onCreateNode/index.ts
index ad1d87fed6..ba36408c91 100644
--- a/data/onCreateNode/index.ts
+++ b/data/onCreateNode/index.ts
@@ -1,5 +1,4 @@
 import { GatsbyNode, Node } from 'gatsby';
-import { transformNanocTextiles, makeTypeFromParentType, createNodesFromPath } from '../transform';
 
 export const onCreateNode: GatsbyNode['onCreateNode'] = async ({
   node,
@@ -8,34 +7,6 @@ export const onCreateNode: GatsbyNode['onCreateNode'] = async ({
   createNodeId,
   createContentDigest,
 }) => {
-  const createChildNode = ({ parent, child }: { parent: Node; child: Node }) => {
-    createNode(child);
-    createParentChildLink({ parent, child });
-  };
-
-  if (node.extension === 'textile') {
-    const content = await loadNodeContent(node);
-    try {
-      transformNanocTextiles(node, content, createNodeId(`${node.id} >>> HTML`), makeTypeFromParentType('Html')(node), {
-        createContentDigest,
-        createNodesFromPath: createNodesFromPath('DocumentPath', { createNode, createNodeId, createContentDigest }),
-        createNodeId,
-      })(createChildNode);
-    } catch (error: unknown) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      const ErrorNode = {
-        id: createNodeId(`${errorMessage} >>> Error`),
-        message: errorMessage,
-        internal: {
-          contentDigest: createContentDigest(errorMessage),
-          type: 'Error',
-        },
-      };
-      createNode(ErrorNode);
-      console.error('Error at relative path:\n', node.relativePath ? `${node.relativePath}\n` : '\n', errorMessage);
-    }
-  }
-
   if (node.sourceInstanceName === 'how-tos') {
     // We derive the name of the how-to from the path
     const [tutorialName, src, ...paths] = (node.relativePath as string).split('/');
diff --git a/data/transform/index.js b/data/transform/index.js
index 3a128c3816..f83b232daf 100644
--- a/data/transform/index.js
+++ b/data/transform/index.js
@@ -93,9 +93,6 @@ const transformNanocTextiles =
       return;
     }
 
-    if (node.sourceInstanceName === 'textile-partials') {
-      content = `${content}\n`;
-    }
     const preTextileTransform = preParser(content);
     const { data, frontmatterMeta } = splitDataAndMetaData(preTextileTransform);
 
@@ -139,14 +136,8 @@ const transformNanocTextiles =
       type,
       mediaType: 'text/html',
     };
-    if (node.sourceInstanceName === 'textile-partials') {
-      newNodeInternals.type = `${type}Partial`;
-      newNodeData.relativePath = node.relativePath;
-    } else {
-      createNodesFromPath(node.relativePath.replace(/\.[^/.]+$/, ''));
-      // Partials should never have a slug, every other page type needs one.
-      newNodeData.slug = slug;
-    }
+    createNodesFromPath(node.relativePath.replace(/\.[^/.]+$/, ''));
+    newNodeData.slug = slug;
 
     const htmlNode = {
       ...newNodeData,
diff --git a/data/transform/parser-enhancements/index.js b/data/transform/parser-enhancements/index.js
index bf5dad7a06..c6d3b44d31 100644
--- a/data/transform/parser-enhancements/index.js
+++ b/data/transform/parser-enhancements/index.js
@@ -1,4 +1,4 @@
-const { addHyphenListSupport } = require('../pre-parser/textile-js-workarounds/add-hyphen-list-support');
+// textile workarounds removed
 const { addDates } = require('./add-dates');
 const { addSpecAnchorLinks } = require('./spec-anchor-links');
 
diff --git a/data/transform/pre-parser/index.ts b/data/transform/pre-parser/index.ts
index 0b4efbd74b..f65f112483 100644
--- a/data/transform/pre-parser/index.ts
+++ b/data/transform/pre-parser/index.ts
@@ -1,6 +1,4 @@
 import { compose } from 'lodash/fp';
-import textile from 'textile-js';
-import { replaceERB } from './erbjs';
 import {
   convertJSAllToNodeAndJavaScript,
   convertBlangBlocksToTokens,
@@ -11,23 +9,12 @@ import {
   addLanguageSupportForHeadings,
 } from './language';
 import { stripComments, addMinimizeForHeadings, addMinimizedIndent } from './semantic';
-import { textileJSCompatibility } from './textile-js-workarounds';
 
-// Newlines before closing tags inhibit textile-js' ability to correctly parse HTML
+// Newlines before closing tags can affect HTML parsing
 export const removeNewlinesBeforeClosingTags: StringTransformation = (content) =>
   content.replace(/\n+(<\/\w+>)/g, '$1');
 
-// Jest has difficulty with resolving recursively-composed functions from different files
-// so we define this textile-js-workaround here.
-export const recursivelyProcessDivs: StringTransformation = (content) =>
-  content.replace(/\n]*?)>\n(.*?)<\/div>/gms, (_match, p1, p2) => {
-    return `\n${textile(preParser(p2)).replace(/\n/g, '')}
`; - }); - export const preParser = compose( - // Textile compatibility must follow all other changes - textileJSCompatibility, - recursivelyProcessDivs, // Language operations addLanguageSupportForHeadings, addLanguageSupportForBlockQuotes, @@ -41,6 +28,4 @@ export const preParser = compose( addMinimizeForHeadings, removeNewlinesBeforeClosingTags, stripComments, - // ERB to JS - replaceERB, ); From 450022ff0df30a1a8740e054d3cba95f7ebd48fb Mon Sep 17 00:00:00 2001 From: Kenneth Kalmer Date: Wed, 26 Nov 2025 21:55:00 +0000 Subject: [PATCH 2/6] Delete textile/ERB infrastructure and test files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove all textile and ERB processing infrastructure code now that the build pipeline no longer uses it. This includes workarounds, utilities, and tests that validated textile parsing behavior. Deleted: - textile-js-workarounds directory (28 files) - erbjs directory (ERB processing, 6 files + tests) - Textile utility files and type definitions - Test files dependent on textile/ERB processing The build continues to work with no textile processing infrastructure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../parser-steps/textile-workarounds.ts | 56 - data/html-parser/README.md | 25 - .../add-info-to-codeblocks.ts | 11 - .../codeblock-api-key-info.ts | 5 - .../codeblock-random-channel-name.ts | 8 - .../duplicate-lang-attributes.fixtures.ts | 71 - .../duplicate-lang-attributes.test.ts | 41 - data/html-parser/duplicate-lang-attributes.ts | 19 - data/html-parser/html-parser.test.js | 155 -- data/html-parser/index.ts | 87 -- data/html-parser/lift-lang-attributes.test.ts | 23 - data/html-parser/lift-lang-attributes.ts | 18 - ...ren-from-pre-wrapped-code-elements.test.ts | 51 - ...children-from-pre-wrapped-code-elements.ts | 16 - ...e-paragraphs-from-definition-lists.test.ts | 78 - ...remove-paragraphs-from-definition-lists.ts | 19 - data/test-utilities/process-textile.ts | 13 - data/textile.d.ts | 5 - data/transform/StringContentOrderedList.d.ts | 6 - data/transform/channel-options.test.ts | 107 -- data/transform/constants.ts | 6 - data/transform/front-matter.ts | 21 - data/transform/index.js | 182 --- data/transform/parser-enhancements/README.md | 23 - .../parser-enhancements/add-dates.js | 10 - data/transform/parser-enhancements/index.js | 14 - .../parser-enhancements/spec-anchor-links.js | 10 - data/transform/post-parser/README.md | 26 - data/transform/post-parser/blang.test.ts | 81 -- data/transform/post-parser/blang.ts | 24 - data/transform/post-parser/constants.ts | 15 - data/transform/post-parser/index.ts | 20 - .../root-level-text-wrapper.test.ts | 49 - .../post-parser/root-level-text-wrapper.ts | 14 - data/transform/pre-parser/README.md | 30 - .../__snapshots__/div-format.test.ts.snap | 830 ----------- data/transform/pre-parser/div-format.test.ts | 132 -- data/transform/pre-parser/erbjs/README.md | 28 - data/transform/pre-parser/erbjs/emoji.test.js | 25 - data/transform/pre-parser/erbjs/emojis.js | 19 - data/transform/pre-parser/erbjs/index.js | 10 - .../transform/pre-parser/erbjs/item-select.js | 8 - .../pre-parser/erbjs/item-select.test.js | 10 - .../pre-parser/erbjs/language-map.js | 37 - .../pre-parser/erbjs/language-map.test.js | 9 - data/transform/pre-parser/index.ts | 31 - .../blang-conversions.test.ts.snap | 184 --- .../language/blang-conversions.test.ts | 127 -- .../pre-parser/language/blang-conversions.ts | 84 -- .../pre-parser/language/blang.raw.examples.ts | 293 ---- .../language/duplicate-blocks.test.ts | 35 - .../pre-parser/language/duplicate-blocks.ts | 46 - .../pre-parser/language/html-support.test.ts | 43 - .../pre-parser/language/html-support.ts | 59 - data/transform/pre-parser/language/index.ts | 5 - .../pre-parser/language/support-for-github.js | 49 - .../language/support-for-github.test.js | 41 - .../pre-parser/language/white-space.js | 20 - data/transform/pre-parser/semantic/index.js | 9 - .../transform/pre-parser/semantic/minimize.js | 48 - .../pre-parser/semantic/minimize.test.js | 68 - .../shared-utilities/extract-indented.ts | 41 - .../textile-js-workarounds/README.md | 9 - .../add-bold-text.test.ts | 15 - .../textile-js-workarounds/add-bold-text.ts | 3 - .../add-hyphen-list-support.test.ts | 41 - .../add-hyphen-list-support.ts | 4 - .../add-italicised-text.test.ts | 7 - .../add-italicised-text.ts | 4 - .../fix-html-tags-with-newlines.ts | 3 - .../fix-inline-code.test.ts | 13 - .../textile-js-workarounds/fix-inline-code.ts | 3 - .../fix-leading-html-tags.test.ts | 9 - .../fix-leading-html-tags.ts | 7 - .../textile-js-workarounds/fix-links.test.ts | 155 -- .../textile-js-workarounds/fix-links.ts | 28 - .../fix-divs-in-definition-lists.ts | 41 - .../fix-h1-6-after-definition-lists.ts | 2 - .../fix-indented-definition-lists.ts | 2 - .../fix-newlines-in-definition-lists.ts | 3 - .../fix-textile-definition-lists.test.ts | 27 - .../fix-textile-definition-lists/index.ts | 10 - .../fix-textile-definition-lists/test-data.ts | 14 - .../textile-js-workarounds/heading.test.ts | 458 ------ .../textile-js-workarounds/index.test.ts | 43 - .../textile-js-workarounds/index.ts | 37 - ...ake-implicit-ordered-list-explicit.test.ts | 40 - .../make-implicit-ordered-list-explicit.ts | 4 - .../missing-spans.test.ts | 1292 ----------------- .../recursively-process-divs.test.ts | 18 - .../workarounds.raw.examples.ts | 150 -- .../retrieve-partials/applyIndent.test.ts | 33 - .../retrieve-partials/applyIndent.ts | 7 - data/transform/retrieve-partials/index.js | 66 - data/transform/shared-utilities/index.js | 18 - data/transform/string-transformation.d.ts | 1 - read-textile.ts | 235 --- .../check-link-is-internal.test.ts | 2 +- ...ConditionalChildrenLanguageDisplay.test.js | 128 -- ...tionalChildrenLanguageDisplay.test.js.snap | 52 - 100 files changed, 1 insertion(+), 6613 deletions(-) delete mode 100644 data/cli-functionality/parser-steps/textile-workarounds.ts delete mode 100644 data/html-parser/README.md delete mode 100644 data/html-parser/add-info-to-codeblocks/add-info-to-codeblocks.ts delete mode 100644 data/html-parser/add-info-to-codeblocks/codeblock-api-key-info.ts delete mode 100644 data/html-parser/add-info-to-codeblocks/codeblock-random-channel-name.ts delete mode 100644 data/html-parser/duplicate-lang-attributes.fixtures.ts delete mode 100644 data/html-parser/duplicate-lang-attributes.test.ts delete mode 100644 data/html-parser/duplicate-lang-attributes.ts delete mode 100644 data/html-parser/html-parser.test.js delete mode 100644 data/html-parser/index.ts delete mode 100644 data/html-parser/lift-lang-attributes.test.ts delete mode 100644 data/html-parser/lift-lang-attributes.ts delete mode 100644 data/html-parser/remove-children-from-pre-wrapped-code-elements.test.ts delete mode 100644 data/html-parser/remove-children-from-pre-wrapped-code-elements.ts delete mode 100644 data/html-parser/remove-paragraphs-from-definition-lists.test.ts delete mode 100644 data/html-parser/remove-paragraphs-from-definition-lists.ts delete mode 100644 data/test-utilities/process-textile.ts delete mode 100644 data/textile.d.ts delete mode 100644 data/transform/StringContentOrderedList.d.ts delete mode 100644 data/transform/channel-options.test.ts delete mode 100644 data/transform/constants.ts delete mode 100644 data/transform/front-matter.ts delete mode 100644 data/transform/index.js delete mode 100644 data/transform/parser-enhancements/README.md delete mode 100644 data/transform/parser-enhancements/add-dates.js delete mode 100644 data/transform/parser-enhancements/index.js delete mode 100644 data/transform/parser-enhancements/spec-anchor-links.js delete mode 100644 data/transform/post-parser/README.md delete mode 100644 data/transform/post-parser/blang.test.ts delete mode 100644 data/transform/post-parser/blang.ts delete mode 100644 data/transform/post-parser/constants.ts delete mode 100644 data/transform/post-parser/index.ts delete mode 100644 data/transform/post-parser/root-level-text-wrapper.test.ts delete mode 100644 data/transform/post-parser/root-level-text-wrapper.ts delete mode 100644 data/transform/pre-parser/README.md delete mode 100644 data/transform/pre-parser/__snapshots__/div-format.test.ts.snap delete mode 100644 data/transform/pre-parser/div-format.test.ts delete mode 100644 data/transform/pre-parser/erbjs/README.md delete mode 100644 data/transform/pre-parser/erbjs/emoji.test.js delete mode 100644 data/transform/pre-parser/erbjs/emojis.js delete mode 100644 data/transform/pre-parser/erbjs/index.js delete mode 100644 data/transform/pre-parser/erbjs/item-select.js delete mode 100644 data/transform/pre-parser/erbjs/item-select.test.js delete mode 100644 data/transform/pre-parser/erbjs/language-map.js delete mode 100644 data/transform/pre-parser/erbjs/language-map.test.js delete mode 100644 data/transform/pre-parser/index.ts delete mode 100644 data/transform/pre-parser/language/__snapshots__/blang-conversions.test.ts.snap delete mode 100644 data/transform/pre-parser/language/blang-conversions.test.ts delete mode 100644 data/transform/pre-parser/language/blang-conversions.ts delete mode 100644 data/transform/pre-parser/language/blang.raw.examples.ts delete mode 100644 data/transform/pre-parser/language/duplicate-blocks.test.ts delete mode 100644 data/transform/pre-parser/language/duplicate-blocks.ts delete mode 100644 data/transform/pre-parser/language/html-support.test.ts delete mode 100644 data/transform/pre-parser/language/html-support.ts delete mode 100644 data/transform/pre-parser/language/index.ts delete mode 100644 data/transform/pre-parser/language/support-for-github.js delete mode 100644 data/transform/pre-parser/language/support-for-github.test.js delete mode 100644 data/transform/pre-parser/language/white-space.js delete mode 100644 data/transform/pre-parser/semantic/index.js delete mode 100644 data/transform/pre-parser/semantic/minimize.js delete mode 100644 data/transform/pre-parser/semantic/minimize.test.js delete mode 100644 data/transform/pre-parser/shared-utilities/extract-indented.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/README.md delete mode 100644 data/transform/pre-parser/textile-js-workarounds/add-bold-text.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/add-bold-text.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/add-hyphen-list-support.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/add-hyphen-list-support.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/add-italicised-text.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/add-italicised-text.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-html-tags-with-newlines.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-inline-code.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-inline-code.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-leading-html-tags.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-leading-html-tags.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-links.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-links.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-divs-in-definition-lists.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-h1-6-after-definition-lists.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-indented-definition-lists.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-newlines-in-definition-lists.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-textile-definition-lists.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/index.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/test-data.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/heading.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/index.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/index.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/make-implicit-ordered-list-explicit.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/make-implicit-ordered-list-explicit.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/missing-spans.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/recursively-process-divs.test.ts delete mode 100644 data/transform/pre-parser/textile-js-workarounds/workarounds.raw.examples.ts delete mode 100644 data/transform/retrieve-partials/applyIndent.test.ts delete mode 100644 data/transform/retrieve-partials/applyIndent.ts delete mode 100644 data/transform/retrieve-partials/index.js delete mode 100644 data/transform/shared-utilities/index.js delete mode 100644 data/transform/string-transformation.d.ts delete mode 100755 read-textile.ts delete mode 100644 src/components/blocks/wrappers/ConditionalChildrenLanguageDisplay.test.js delete mode 100644 src/components/blocks/wrappers/__snapshots__/ConditionalChildrenLanguageDisplay.test.js.snap diff --git a/data/cli-functionality/parser-steps/textile-workarounds.ts b/data/cli-functionality/parser-steps/textile-workarounds.ts deleted file mode 100644 index abec7aa2d7..0000000000 --- a/data/cli-functionality/parser-steps/textile-workarounds.ts +++ /dev/null @@ -1,56 +0,0 @@ -import { fixImgTagsWithNewlines } from '../../../data/transform/pre-parser/textile-js-workarounds/fix-html-tags-with-newlines'; -import { fixInlineCode } from '../../../data/transform/pre-parser/textile-js-workarounds/fix-inline-code'; -import { fixLeadingHtmlTags } from '../../../data/transform/pre-parser/textile-js-workarounds/fix-leading-html-tags'; -import { - fixDuplicateQuoteLinks, - fixHtmlElementsInLinks, - fixPunctuationInLinks, -} from '../../../data/transform/pre-parser/textile-js-workarounds/fix-links'; -import { fixTextileDefinitionLists } from '../../../data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists'; -import { makeImplicitOrderedListExplicit } from '../../../data/transform/pre-parser/textile-js-workarounds/make-implicit-ordered-list-explicit'; -import { - compressMultipleNewlinesInLists, - manuallyReplaceHTags, -} from '../../../data/transform/pre-parser/textile-js-workarounds'; -import { addBoldText } from '../../../data/transform/pre-parser/textile-js-workarounds/add-bold-text'; -import { addItalicisedText } from '../../../data/transform/pre-parser/textile-js-workarounds/add-italicised-text'; -import { Step } from './pre-parser'; - -export const textileWorkaroundSteps: Step[] = [ - { - fn: addBoldText, - }, - { - fn: addItalicisedText, - }, - { - fn: fixHtmlElementsInLinks, - }, - { - fn: fixPunctuationInLinks, - }, - { - fn: fixDuplicateQuoteLinks, - }, - { - fn: fixImgTagsWithNewlines, - }, - { - fn: manuallyReplaceHTags, - }, - { - fn: makeImplicitOrderedListExplicit, - }, - { - fn: compressMultipleNewlinesInLists, - }, - { - fn: fixInlineCode, - }, - { - fn: fixTextileDefinitionLists, - }, - { - fn: fixLeadingHtmlTags, - }, -]; diff --git a/data/html-parser/README.md b/data/html-parser/README.md deleted file mode 100644 index dd4de1bc55..0000000000 --- a/data/html-parser/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# HTML Parser - -The HTML parser directory is intended for manipulations that are most easily executed using jQuery (Cheerio) transformations on HTML. - -It is the final stage in the data ingestion process before HTML is transformed into data for GraphQL/for the main documentation application. - -## Compare - -1. [Pre-parser](../transform/pre-parser/README.md) - transforms plain text to plain text ready to be parsed. -2. [Parser enhancements](../transform/parser-enhancements/README.md) - transforms data with enhancements from `attributes` and document `path`. -2. [Post-parser](../transform/post-parser/README.md) - transforms data after it has been parsed by a dedicated parser such as `textile-js`. -4. Component mapping - maps `{ data, type }` objects to React components based on `type`. -5. React components - standardise the behaviour, presentation, layout and markup semantics of `data` from `{ data, type }` objects. - -## Usage - -It is a good place to put: -* Operations that are too expensive to carry out on the client's machine. -* Operations that may be complicated to implement for the data provided to the client's machine, for which jQuery/Cheerio has well-tested existing functions. -* Behaviour that is implemented in jQuery on the legacy toolchain or via. the website in jQuery on the legacy toolchain that we do not want to risk changing. - -It is not the best place to put: -* Changes in HTML behaviour that allow for interactivity or which affect component functionality. -* Most changes that are not directed at HTML components. -* Fixes for strange parser behaviour. \ No newline at end of file diff --git a/data/html-parser/add-info-to-codeblocks/add-info-to-codeblocks.ts b/data/html-parser/add-info-to-codeblocks/add-info-to-codeblocks.ts deleted file mode 100644 index c28bc39a33..0000000000 --- a/data/html-parser/add-info-to-codeblocks/add-info-to-codeblocks.ts +++ /dev/null @@ -1,11 +0,0 @@ -import cheerio from 'cheerio'; - -export const addInfoToCodeBlock = - (tokenIdentifier: string, dataAttributeName: string) => (cheerioNodes: cheerio.Selector) => - cheerioNodes('pre > code').each((_, elem) => { - const loadedCodeElement = cheerioNodes(elem); - const content = loadedCodeElement.text(); - if (content.includes(`{{${tokenIdentifier}}}`)) { - cheerioNodes(elem).attr(`data-contains-${dataAttributeName}`, 'true'); - } - }); diff --git a/data/html-parser/add-info-to-codeblocks/codeblock-api-key-info.ts b/data/html-parser/add-info-to-codeblocks/codeblock-api-key-info.ts deleted file mode 100644 index 65e4b5c283..0000000000 --- a/data/html-parser/add-info-to-codeblocks/codeblock-api-key-info.ts +++ /dev/null @@ -1,5 +0,0 @@ -import { addInfoToCodeBlock } from './add-info-to-codeblocks'; - -export const API_KEY_DATA_ATTRIBUTE = 'key'; - -export const addAPIKeyInfoToCodeBlock = addInfoToCodeBlock('API_KEY', API_KEY_DATA_ATTRIBUTE); diff --git a/data/html-parser/add-info-to-codeblocks/codeblock-random-channel-name.ts b/data/html-parser/add-info-to-codeblocks/codeblock-random-channel-name.ts deleted file mode 100644 index 07eaebfc11..0000000000 --- a/data/html-parser/add-info-to-codeblocks/codeblock-random-channel-name.ts +++ /dev/null @@ -1,8 +0,0 @@ -import { addInfoToCodeBlock } from './add-info-to-codeblocks'; - -export const RANDOM_CHANNEL_NAME_DATA_ATTRIBUTE = 'random-channel'; - -export const addRandomChannelInfoToCodeBlock = addInfoToCodeBlock( - 'RANDOM_CHANNEL_NAME', - RANDOM_CHANNEL_NAME_DATA_ATTRIBUTE, -); diff --git a/data/html-parser/duplicate-lang-attributes.fixtures.ts b/data/html-parser/duplicate-lang-attributes.fixtures.ts deleted file mode 100644 index 5d64395fd4..0000000000 --- a/data/html-parser/duplicate-lang-attributes.fixtures.ts +++ /dev/null @@ -1,71 +0,0 @@ -export const brokenCodeAlternativesInsideBlangExample = `

Authentication

-
- -

The client requires authentication in order to establish a connection with Ably. There are three methods that can be used:

-
    -
  1. Basic authentication
    2. -
  2. Token authentication
    3. -
  3. JWT authentication
    4. -
-

Usually a client will use either token or JWT authentication, as basic authentication would require exposing the API keys on the client.

-

Examples of establishing a connection using the three methods are given in the following sections. While the examples shown are for either the Publishing or Subscribing SDK, you can use the same approach for both SDKs.

-

Basic Authentication

-

The following example demonstrates establishing a connection using basic authentication:

- 

-      val publisher = Publisher.publishers() // get the Publisher builder in default state
-        .connection(ConnectionConfiguration(Authentication.basic(CLIENT_ID, ABLY_API_KEY)))
-
-
- 

-      const subscriber = new Subscriber({ key: 'ABLY_API_KEY' })
-
-
-

This method should not be used on a client however, as it exposes the API key.

-

You can read more about basic authentication in our documentation.

-

Token Authentication

-

The following example demonstrates establishing a connection using token authentication:

- 

-      val publisher = Publisher.publishers() // get the Publisher builder in default state
-          .connection(ConnectionConfiguration(Authentication.tokenRequest(CLIENT_ID) { requestParameters ->
-              // get TokenRequest from your server
-              getTokenRequestFromAuthServer(requestParameters); // customer implements this function
-              }))
-
-
- 

-      /* authURL is the endpoint for your authentication server. It returns either
-        a \`TokenRequest\` or a \`Token\` */
-      const subscriber = new Subscriber({
-        authUrl: 'http://my.website/auth',
-        clientId: 'CLIENT_ID'
-      })
-
-
-

You can read more about token authentication in our documentation.

-

JWT Authentication

-

The following example demonstrates establishing a connection using JWT authentication:

- 

-      val publisher = Publisher.publishers() // get the Publisher builder in default state
-        .connection(ConnectionConfiguration(Authentication.jwt(CLIENT_ID) { tokenParameters ->
-              // get JWT from your server
-              getJWTFromAuthServer(tokenParameters); // customer implements this function
-              }))
-
-
- 

-      // authURL is the endpoint for your authentication server. It returns a JWT
-      const subscriber = new Subscriber({
-        authUrl: 'http://my.website/auth',
-        clientId: 'CLIENT_ID'
-      })
-
-
-

You can read more about JWT authentication in our documentation.

- -

The client requires authentication in order to establish a connection with Ably. Currently, the Swift SDK only supports basic authentication: you authenticate with your Ably API key (available in your account dashboard and can optionally identify the client with a client ID. The following example demonstrates how to achieve this:

-

\`\`\`[swift]
- let publisher = try PublisherFactory.publishers() // get a Publisher builder
- .connection(ConnectionConfiguration(apiKey: ABLY_API_KEY, - clientId: CLIENT_ID))
- /* Any additional configuration */
- .start()

\`\`\``; diff --git a/data/html-parser/duplicate-lang-attributes.test.ts b/data/html-parser/duplicate-lang-attributes.test.ts deleted file mode 100644 index cf5355f9af..0000000000 --- a/data/html-parser/duplicate-lang-attributes.test.ts +++ /dev/null @@ -1,41 +0,0 @@ -import cheerio from 'cheerio'; -import { duplicateLangAttributes } from './duplicate-lang-attributes'; - -const content = `
Content
`; - -const nestedSpanContent = `
-
-

on(String[] events, listener(ChannelStateChange stateChange))

-
-

Same as above, but registers multiple listeners, one for each event in the array.

-
`; - -describe('Duplicate language blocks with commas', () => { - it('Duplicates language blocks with commas', () => { - const loadedDom = cheerio.load(content); - duplicateLangAttributes(loadedDom); - expect(loadedDom.html().replace(/\s+/g, '')).toEqual( - ` -
Content
-
Content
-
Content
- `.replace(/\s+/g, ''), - ); - }); - - it('Duplicates nested span language blocks with commas', () => { - const loadedDom = cheerio.load(nestedSpanContent); - duplicateLangAttributes(loadedDom); - expect(loadedDom.html().replace(/\s+/g, '')).toEqual( - `
-
-

- on(String[] events, listener(ChannelStateChange stateChange)) - on(String[] events, listener(ChannelStateChange stateChange)) -

-
-

Same as above, but registers multiple listeners, one for each event in the array.

-
`.replace(/\s+/g, ''), - ); - }); -}); diff --git a/data/html-parser/duplicate-lang-attributes.ts b/data/html-parser/duplicate-lang-attributes.ts deleted file mode 100644 index bfd52d6ea1..0000000000 --- a/data/html-parser/duplicate-lang-attributes.ts +++ /dev/null @@ -1,19 +0,0 @@ -import cheerio from 'cheerio'; - -export const duplicateLangAttributes = (cheerioNodes: cheerio.Selector) => { - const cheerioNodesToRemove: cheerio.Cheerio[] = []; - cheerioNodes('*[lang]').each((_, elem) => { - const maybeLanguages = cheerioNodes(elem).attr('lang'); - if (!maybeLanguages || /^[^,]+$/.test(maybeLanguages)) { - return; - } - const langs = maybeLanguages.split(','); - const node = cheerioNodes(elem); - duplicateLangAttributes(node.find.bind(node)); - langs.forEach((lang) => { - cheerioNodes(elem).clone().attr('lang', lang).insertAfter(cheerioNodes(elem)); - }); - cheerioNodesToRemove.push(node); - }); - cheerioNodesToRemove.forEach((node) => node.remove()); -}; diff --git a/data/html-parser/html-parser.test.js b/data/html-parser/html-parser.test.js deleted file mode 100644 index 4c30661064..0000000000 --- a/data/html-parser/html-parser.test.js +++ /dev/null @@ -1,155 +0,0 @@ -import * as fc from 'fast-check'; -import { cheerioNodeParser, htmlParser } from '.'; -import htmlString from '../../test-generators.js/html'; -import HtmlDataTypes from '../types/html'; - -const buildExpectedFromTagArray = (tagArray, innerText) => - tagArray.length === 0 - ? [ - { - data: innerText, - type: HtmlDataTypes.text, - name: HtmlDataTypes.text, - }, - ] - : [ - { - data: buildExpectedFromTagArray(tagArray.slice(1), innerText), - type: HtmlDataTypes.tag, - name: tagArray[0], - attribs: Object.create(null), - }, - ]; - -describe('Cheerio node parser transforms data as expected', () => { - it('A single text node has no attributes', () => { - const input = { - children: [], - attribs: {}, - data: 'Lorem ipsum dolor sit mae adipiscing color', - name: HtmlDataTypes.text, - type: HtmlDataTypes.text, - }; - const expected = { - data: 'Lorem ipsum dolor sit mae adipiscing color', - name: HtmlDataTypes.text, - type: HtmlDataTypes.text, - }; - const actual = cheerioNodeParser(null, input); - expect(actual).toEqual(expected); - }); - it('A node with children has them moved into the data property', () => { - const input = { - children: [ - { - children: [], - attribs: {}, - data: 'Lorem ipsum dolor sit mae adipiscing color', - name: 'text', - type: 'text', - }, - ], - attribs: {}, - type: HtmlDataTypes.tag, - name: HtmlDataTypes.p, - }; - const expected = { - data: [ - { - data: 'Lorem ipsum dolor sit mae adipiscing color', - name: 'text', - type: 'text', - }, - ], - type: HtmlDataTypes.tag, - name: HtmlDataTypes.p, - attribs: {}, - }; - const actual = cheerioNodeParser(null, input); - expect(actual).toEqual(expected); - }); -}); - -describe('HTML parsing into data objects works as expected', () => { - // The behaviour of invalid HTML is defined by Cheerio and beyond the scope of this testing suite unless specific examples cause issues. - it('A specific, known-valid piece of HTML is capable of being interpreted into data objects in the correct format by the HTML parser', () => { - const validHtml = - '

Lorem ipsum dolor sit mae adipiscing color

' + - '

insertium paragraphicus loremitor

' + - '
A good example of some common text with text both in and out of elements.
'; - const expected = [ - { - attribs: {}, - data: [ - { - data: 'Lorem ipsum dolor sit mae adipiscing color', - name: 'text', - type: 'text', - }, - ], - name: 'p', - type: 'tag', - }, - { - attribs: {}, - data: [ - { - data: 'insertium paragraphicus ', - name: 'text', - type: 'text', - }, - { - attribs: {}, - data: [ - { - data: 'loremitor', - name: 'text', - type: 'text', - }, - ], - name: 'strong', - type: 'tag', - }, - ], - name: 'p', - type: 'tag', - }, - { - attribs: {}, - data: [ - { - attribs: {}, - data: [ - { - data: 'A good example of some common text', - name: 'text', - type: 'text', - }, - ], - name: 'span', - type: 'tag', - }, - { - data: ' with text both in and out of elements.', - name: 'text', - type: 'text', - }, - ], - name: 'div', - type: 'tag', - }, - ]; - const [{ data: actual }] = htmlParser(validHtml); - expect(actual).toEqual(expected); - }); - - it('Arbitrary valid HTML is capable of being interpreted into data objects in the correct format by the HTML parser', () => { - fc.assert( - fc.property(htmlString, ({ result, tagResult, innerText }) => { - const [{ data: actual }] = htmlParser(result); - const expected = buildExpectedFromTagArray(tagResult, innerText); - expect(actual).toEqual(expected); - }), - ); - }); -}); diff --git a/data/html-parser/index.ts b/data/html-parser/index.ts deleted file mode 100644 index cfc53fa241..0000000000 --- a/data/html-parser/index.ts +++ /dev/null @@ -1,87 +0,0 @@ -// Essentially jQuery for parsing the DOM -import cheerio from 'cheerio'; -import { defaults, pickAll } from 'lodash/fp'; -import DataTypes from '../types'; -import HtmlDataTypes from '../types/html'; -import { addAPIKeyInfoToCodeBlock } from './add-info-to-codeblocks/codeblock-api-key-info'; -import { addRandomChannelInfoToCodeBlock } from './add-info-to-codeblocks/codeblock-random-channel-name'; -import { duplicateLangAttributes } from './duplicate-lang-attributes'; -import { liftLangAttributes } from './lift-lang-attributes'; -import { removeChildrenFromPreWrappedCodeElements } from './remove-children-from-pre-wrapped-code-elements'; -import { removeParagraphsFromDefinitionListsAndMerge } from './remove-paragraphs-from-definition-lists'; - -type Attributes = { [attr: string]: string }; - -type HtmlDataType = keyof typeof HtmlDataTypes; - -/** - * Data that we need to check from any cheerio element to see what to do with it - */ -type AnyCheerioElement = { - type?: null | 'text' | 'tag' | 'script' | 'style' | 'comment'; - name: HtmlDataType; - data: string; - attribs?: null | Attributes; - children: cheerio.Element[]; -}; - -type ParsedNode = { - data: string | ParsedNode[]; - type: typeof HtmlDataTypes.text | typeof HtmlDataTypes.tag; - name: string; - attribs?: null | Attributes; -}; - -export const cheerioNodeParser = (_i: number, node: cheerio.Element): ParsedNode => { - const { type, name, data, attribs, children }: AnyCheerioElement = defaults( - { - type: null, - name: HtmlDataTypes.text, - data: '', - attribs: {}, - children: [], - }, - pickAll(['type', 'name', 'data', 'attribs', 'children'], node), - ); - if (!type || type === HtmlDataTypes.text) { - return { - data, - type: HtmlDataTypes.text, - name: HtmlDataTypes.text, - }; - } - const nextItems: ParsedNode[] = children.map((data, i) => cheerioNodeParser(i, data)); - return { - data: nextItems, - type: HtmlDataTypes.tag, - name: HtmlDataTypes[name] ?? DataTypes.Html, - attribs, - }; -}; - -export const cheerioParser = (cheerioNodes: cheerio.Cheerio) => { - const data = cheerioNodes.map(cheerioNodeParser); - return data.toArray(); -}; - -export const loadAndAlterHtml = (content: string) => { - const loadedDom = cheerio.load(content); - liftLangAttributes(loadedDom); - duplicateLangAttributes(loadedDom); - addAPIKeyInfoToCodeBlock(loadedDom); - addRandomChannelInfoToCodeBlock(loadedDom); - removeParagraphsFromDefinitionListsAndMerge(loadedDom); - removeChildrenFromPreWrappedCodeElements(loadedDom); - return loadedDom('body').children('*'); -}; - -export const htmlParser = (content: string) => { - const loadedDomBodyNodes = loadAndAlterHtml(content); - const parsedNodes = cheerioParser(loadedDomBodyNodes); - return [ - { - data: parsedNodes, - type: DataTypes.Html, - }, - ]; -}; diff --git a/data/html-parser/lift-lang-attributes.test.ts b/data/html-parser/lift-lang-attributes.test.ts deleted file mode 100644 index ceedbb7560..0000000000 --- a/data/html-parser/lift-lang-attributes.test.ts +++ /dev/null @@ -1,23 +0,0 @@ -import cheerio from 'cheerio'; -import { liftLangAttributes } from './lift-lang-attributes'; - -const content = `
-
Term
-
Definition
-
`; - -describe('Lift language attributes into
and
elements', () => { - it('Lifts language attributes into
and
elements', () => { - const loadedDom = cheerio.load(content); - liftLangAttributes(loadedDom); - const html = loadedDom('body').html() ?? ''; - expect(html.replace(/\s+/g, '')).toEqual( - `
-
-
Term
-
Definition
-
-
`.replace(/\s+/g, ''), - ); - }); -}); diff --git a/data/html-parser/lift-lang-attributes.ts b/data/html-parser/lift-lang-attributes.ts deleted file mode 100644 index b48f7ec787..0000000000 --- a/data/html-parser/lift-lang-attributes.ts +++ /dev/null @@ -1,18 +0,0 @@ -import cheerio from 'cheerio'; - -type FixedCheerio = - | cheerio.Cheerio & { - wrapAll(content: string): cheerio.Cheerio; - wrapAll(content: unknown): cheerio.Cheerio; - wrapAll(content: cheerio.Cheerio): cheerio.Cheerio; - }; - -/** Source: Ably 'docs' repo ./app/assets/javascripts/lang-manager.js ll.61-66 */ -export const liftLangAttributes = (cheerioNodes: cheerio.Selector) => - cheerioNodes('dl dt > div[lang]').each((_i: number, elem: cheerio.Element) => { - const lang = cheerioNodes(elem).attr('lang'); - // Workaround for missing types - const singleDtWithDds: FixedCheerio = cheerioNodes(elem).parent('dt').nextUntil('dt').addBack(); - singleDtWithDds.wrapAll(`
`); - cheerioNodes(elem).removeAttr('lang'); - }); diff --git a/data/html-parser/remove-children-from-pre-wrapped-code-elements.test.ts b/data/html-parser/remove-children-from-pre-wrapped-code-elements.test.ts deleted file mode 100644 index ec672de621..0000000000 --- a/data/html-parser/remove-children-from-pre-wrapped-code-elements.test.ts +++ /dev/null @@ -1,51 +0,0 @@ -import cheerio from 'cheerio'; -import { postParser } from '../transform/post-parser'; -import { preParser } from '../transform/pre-parser'; -import textile from 'textile-js'; -import { removeChildrenFromPreWrappedCodeElements } from './remove-children-from-pre-wrapped-code-elements'; - -type CheerioMutator = (cheerioNodes: cheerio.Selector) => void; - -const loadAndMutateDom = (f: CheerioMutator) => (content: string) => { - const loadedDom = cheerio.load(content); - f(loadedDom); - return loadedDom; -}; - -const getDomWithoutChildrenFromPreWrappedCodeElements = loadAndMutateDom(removeChildrenFromPreWrappedCodeElements); - -const htmlEnclosedContent = `

-    
Term

-    
Definition

-
`; - -const githubEnclosedContent = postParser( - textile( - preParser(`\`\`\`[ruby] -EventMachine.run do - ably = Ably::Realtime.new(key: api_key) -end -\`\`\``), - ), -); - -describe('Safely remove children from pre-wrapped code elements', () => { - it('Removes unwanted HTML elements from code', () => { - const loadedDom = getDomWithoutChildrenFromPreWrappedCodeElements(htmlEnclosedContent); - const html = loadedDom('body').html() ?? ''; - expect(html).toBe(`

-    Term
-    Definition
-
`); - }); - it('Ensures Github code blocks are parsed correctly', () => { - const loadedDom = getDomWithoutChildrenFromPreWrappedCodeElements(githubEnclosedContent); - const html = loadedDom('body').html() ?? ''; - expect(html).toBe(`

-EventMachine.run do
-  ably = Ably::Realtime.new(key: api_key)
-end
-
-
`); - }); -}); diff --git a/data/html-parser/remove-children-from-pre-wrapped-code-elements.ts b/data/html-parser/remove-children-from-pre-wrapped-code-elements.ts deleted file mode 100644 index fbb5de298b..0000000000 --- a/data/html-parser/remove-children-from-pre-wrapped-code-elements.ts +++ /dev/null @@ -1,16 +0,0 @@ -import cheerio from 'cheerio'; - -// This is necessary because highlighting code content is made more complicated if a code element contains HTML elements as children. -// Pre-wrapped elements should not usually contain child elements anyway, the code should be plain text. -export const removeChildrenFromPreWrappedCodeElements = (cheerioNodes: cheerio.Selector) => { - cheerioNodes('pre > code').each((_i, elem) => { - const textNodeContent: string[] = []; - cheerioNodes(elem) - .find('> *') - .each((_i, el) => { - const node = cheerioNodes(el); - node.replaceWith(node.text()); - }); - cheerioNodes(elem).append(textNodeContent.join('\n')); - }); -}; diff --git a/data/html-parser/remove-paragraphs-from-definition-lists.test.ts b/data/html-parser/remove-paragraphs-from-definition-lists.test.ts deleted file mode 100644 index fb2d93b7c6..0000000000 --- a/data/html-parser/remove-paragraphs-from-definition-lists.test.ts +++ /dev/null @@ -1,78 +0,0 @@ -import cheerio from 'cheerio'; -import { removeParagraphsFromDefinitionListsAndMerge } from './remove-paragraphs-from-definition-lists'; - -const consecutiveDls = `
-
Term One
-
Definition One
-
-
-
Term Two
-
Definition Two
-
Term Two
-
Definition Three
-
`; - -const consecutiveDlsWithPElement = `
-
Term One
-
Definition One
-
-

-
-
Term Two
-
Definition Two
-
Term Two
-
Definition Three
-
`; - -describe('Consecutive Dl elements are merged', () => { - it('Merges consecutive Dl elements', () => { - const loadedDom = cheerio.load(consecutiveDls); - removeParagraphsFromDefinitionListsAndMerge(loadedDom); - expect(loadedDom.html()).toBe(`
-
Term One
-
Definition One
-
Term Two
Definition Two
Term Two
Definition Three
-`); - }); - it('Merges consecutive Dl elements with intervening empty p element', () => { - const loadedDom = cheerio.load(consecutiveDlsWithPElement); - removeParagraphsFromDefinitionListsAndMerge(loadedDom); - expect(loadedDom.html()).toBe(`
-
Term One
-
Definition One
-
Term Two
Definition Two
Term Two
Definition Three
- -`); - }); - - it('Renders an image if a dl is on the same page', () => { - const loadedDom = - cheerio.load(`

Ably’s presence feature allows clients or devices to announce their presence on a channel. Other devices or services may then subscribe to these presence events (such as entering, updating their state, or leaving the channel) in real time using our realtime SDKs, or via the Ably Integrations. You can also request a list of clients or devices that are online/offline on a channel at a particular point in time via the REST API.

-

- \\"Presence

-

Furthermore, if persistence is enabled on the presence channel, you can also retrieve presence history for the channel, i.e, static data about historical presence states of your clients/devices. This operation also can be done using both Ably’s Realtime and REST libraries.

-

Occupancy and presence

-

The occupancy and presence features differ in the following ways:

-
-
Occupancy
-
provides metrics about the clients attached to a channel. This includes a count of the number of clients attached, the number of publishers and subscribers, the number of presence members, and the number of presence publishers and subscribers.
-
Presence
-
provides information about the activity of members entered into the presence set of a channel. Presence members announce their state to presence subscribers via presence events. For example, when entering the presence set, leaving the presence set, or updating their member data.
-
`); - removeParagraphsFromDefinitionListsAndMerge(loadedDom); - expect(loadedDom.html()).toMatchInlineSnapshot(` - "

Ably’s presence feature allows clients or devices to announce their presence on a channel. Other devices or services may then subscribe to these presence events (such as entering, updating their state, or leaving the channel) in real time using our realtime SDKs, or via the Ably Integrations. You can also request a list of clients or devices that are online/offline on a channel at a particular point in time via the REST API.

-

- \\"Presence

-

Furthermore, if persistence is enabled on the presence channel, you can also retrieve presence history for the channel, i.e, static data about historical presence states of your clients/devices. This operation also can be done using both Ably’s Realtime and REST libraries.

-

Occupancy and presence

-

The occupancy and presence features differ in the following ways:

-
-
Occupancy
-
provides metrics about the clients attached to a channel. This includes a count of the number of clients attached, the number of publishers and subscribers, the number of presence members, and the number of presence publishers and subscribers.
-
Presence
-
provides information about the activity of members entered into the presence set of a channel. Presence members announce their state to presence subscribers via presence events. For example, when entering the presence set, leaving the presence set, or updating their member data.
-
" - `); - }); -}); diff --git a/data/html-parser/remove-paragraphs-from-definition-lists.ts b/data/html-parser/remove-paragraphs-from-definition-lists.ts deleted file mode 100644 index 056e2803d8..0000000000 --- a/data/html-parser/remove-paragraphs-from-definition-lists.ts +++ /dev/null @@ -1,19 +0,0 @@ -export const removeParagraphsFromDefinitionListsAndMerge = (cheerioNodes: cheerio.Selector) => - cheerioNodes('dl').each((_i: number, elem: cheerio.Element) => { - // As jQuery/Cheerio is stateful and imperative, including comments to clarify - // Remove empty paragraphs immediately after any dl - const siblings = cheerioNodes(elem) - .siblings('p') - .filter((_, elem) => { - const self = cheerioNodes(elem); - const hasHtml = self.html(); - return hasHtml !== null && hasHtml.trim() === ''; - }); - if (siblings.length) { - siblings.remove(); - } - // Now merge multiple consecutive dls - const nextDl = cheerioNodes(elem).nextUntil(':not(dl)'); - cheerioNodes(elem).append(nextDl.children()); - nextDl.remove(); - }); diff --git a/data/test-utilities/process-textile.ts b/data/test-utilities/process-textile.ts deleted file mode 100644 index 08255a004f..0000000000 --- a/data/test-utilities/process-textile.ts +++ /dev/null @@ -1,13 +0,0 @@ -import { cheerioParser, loadAndAlterHtml } from '../html-parser'; -import { postParser } from '../transform/post-parser'; -import { compose } from 'lodash/fp'; -import textile from 'textile-js'; -import { preParser } from '../transform/pre-parser'; - -export const textileToHtml = compose(postParser, textile, preParser); - -export const textileToCheerio = compose(loadAndAlterHtml, textileToHtml); - -export const processTextile = compose((cheerio: cheerio.Cheerio) => cheerio.toArray(), textileToCheerio); - -export const fullyParseTextile = compose(cheerioParser, textileToCheerio); diff --git a/data/textile.d.ts b/data/textile.d.ts deleted file mode 100644 index 2b5e08511c..0000000000 --- a/data/textile.d.ts +++ /dev/null @@ -1,5 +0,0 @@ -declare module 'textile-js' { - type TextileFunction = (input: string) => string; - const textile: TextileFunction; - export default textile; -} diff --git a/data/transform/StringContentOrderedList.d.ts b/data/transform/StringContentOrderedList.d.ts deleted file mode 100644 index b770e6a875..0000000000 --- a/data/transform/StringContentOrderedList.d.ts +++ /dev/null @@ -1,6 +0,0 @@ -export type StringContent = { - data: string; - type: string; -}; - -export type StringContentList = StringContent[]; diff --git a/data/transform/channel-options.test.ts b/data/transform/channel-options.test.ts deleted file mode 100644 index 719c37efcd..0000000000 --- a/data/transform/channel-options.test.ts +++ /dev/null @@ -1,107 +0,0 @@ -import { textileToHtml } from '../../data/test-utilities/process-textile'; -import { preParser } from './pre-parser'; - -const dubiousBlangFixture = ` -h4. - default: Properties - java: Members - ruby: Attributes - -blang[default]. - - :cipherCipherParamscipher := Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See "an example":/realtime/encryption#getting-started
__Type: "@CipherParams@":/api/realtime-sdk/encryption#cipher-params or an options object containing at a minimum a @key@ or a @Param[]@ list containing at a minimum a @key@ or an options hash containing at a minimum a @key@ or an Associative Array containing at a minimum a @key@__ - -blang[jsall,java,swift,objc,csharp]. -- paramsParams := Optional "parameters":/realtime/channels/channel-parameters/overview which specify behaviour of the channel.
__Type: @Map@@JSON Object@__ -- cipherCipherParams := Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See "an example":/api/realtime-sdk/encryption#getting-started
__Type: "@CipherParams@":/api/realtime-sdk/encryption#cipher-params or an options object containing at a minimum a @key@ or a @Param[]@ list containing at a minimum a @key@ or an options hash containing at a minimum a @key@ or an Associative Array containing at a minimum a @key@__ - -blang[java]. -h4. Static methods - -h6(#with-cipher-key). withCipherKey - -bq(definition). static ChannelOptions.withCipherKey(Byte[] or String key) - -A helper method to generate a @ChannelOptions@ for the simple case where you only specify a key. - -h4. Parameters - -- key := A binary @Byte[]@ array or a base64-encoded @String@. - -h4. Returns - -On success, the method returns a complete @ChannelOptions@ object. Failure will raise an "@AblyException@":/api/realtime-sdk/types#ably-exception.`; - -describe('Test channel options rendering', () => { - it('Ensures channel options renders correctly', () => { - expect(preParser(dubiousBlangFixture)).toMatchInlineSnapshot(` - " -

PropertiesMembersAttributes

- - - {{LANG_BLOCK[default]}} - - - :cipherCipherParamscipher := Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type: CipherParams or an options object containing at a minimum a key or a Param[] list containing at a minimum a key or an options hash containing at a minimum a key or an Associative Array containing at a minimum a key - - {{/LANG_BLOCK}} - - - {{LANG_BLOCK[javascript,nodejs,java,swift,objc,csharp]}} - - {{/LANG_BLOCK}} - - - paramsParams := Optional parameters which specify behaviour of the channel.
Type: MapJSON Object - - cipherCipherParams := Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type: CipherParams or an options object containing at a minimum a key or a Param[] list containing at a minimum a key or an options hash containing at a minimum a key or an Associative Array containing at a minimum a key - - - {{LANG_BLOCK[java]}} - - {{/LANG_BLOCK}} - -

Static methods

- -
withCipherKey
- - bq(definition). static ChannelOptions.withCipherKey(Byte[] or String key) - - A helper method to generate a ChannelOptions for the simple case where you only specify a key. - -

Parameters

- - - key := A binary Byte[] array or a base64-encoded String. - -

Returns

- - On success, the method returns a complete ChannelOptions object. Failure will raise an "AblyException":/api/realtime-sdk/types#ably-exception." - `); - expect(textileToHtml(dubiousBlangFixture)).toMatchInlineSnapshot(` - "

PropertiesMembersAttributes

-
- -
-
:cipherCipherParamscipher
-
Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type: CipherParams or an options object containing at a minimum a key or a Param[] list containing at a minimum a key or an options hash containing at a minimum a key or an Associative Array containing at a minimum a key
-
-
-
paramsParams
-
Optional parameters which specify behaviour of the channel.
Type: Map<String, String>JSON Object
-
cipherCipherParams
-
Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type: CipherParams or an options object containing at a minimum a key or a Param[] list containing at a minimum a key or an options hash containing at a minimum a key or an Associative Array containing at a minimum a key
-
-

-
-

Static methods

-

withCipherKey

-
-

static ChannelOptions.withCipherKey(Byte[] or String key)

-
-

A helper method to generate a ChannelOptions for the simple case where you only specify a key.

-

Parameters

-
-
key
-
A binary Byte[] array or a base64-encoded String.
-
-

Returns

-

On success, the method returns a complete ChannelOptions object. Failure will raise an AblyException.

" - `); - }); -}); diff --git a/data/transform/constants.ts b/data/transform/constants.ts deleted file mode 100644 index 36cd1542f8..0000000000 --- a/data/transform/constants.ts +++ /dev/null @@ -1,6 +0,0 @@ -export const LATEST_ABLY_API_VERSION = 1.2; -export const LATEST_ABLY_API_VERSION_STRING = `${LATEST_ABLY_API_VERSION}`; -export const ARTICLE_TYPES = { - document: 'document', - apiReference: 'apiReference', -} as const; diff --git a/data/transform/front-matter.ts b/data/transform/front-matter.ts deleted file mode 100644 index d845725073..0000000000 --- a/data/transform/front-matter.ts +++ /dev/null @@ -1,21 +0,0 @@ -import fm from 'front-matter'; -import { assign, isArray, isEmpty, pick } from 'lodash'; - -export const NO_MATCH = false; -const ALLOWED_META_FIELDS = ['title', 'meta_description', 'languages', 'redirect_from', 'product']; - -const maybeStringToStringSingletonArray = (maybeString?: string | string[]) => - isEmpty(maybeString) ? undefined : isArray(maybeString) ? maybeString : [maybeString]; - -export const tryRetrieveMetaData = (metaDataString: string) => { - const frontMatter = fm(metaDataString); - return isEmpty(frontMatter.attributes) ? NO_MATCH : frontMatter; -}; - -export const filterAllowedMetaFields = (metaObject: Record) => - pick(metaObject, ALLOWED_META_FIELDS); - -export const prepareAllowedMetaFields = (metaObject: Record) => - assign(metaObject, { - redirect_from: maybeStringToStringSingletonArray(metaObject.redirect_from), - }); diff --git a/data/transform/index.js b/data/transform/index.js deleted file mode 100644 index f83b232daf..0000000000 --- a/data/transform/index.js +++ /dev/null @@ -1,182 +0,0 @@ -const { upperFirst, camelCase } = require('lodash'); -const { tryRetrieveMetaData, filterAllowedMetaFields, NO_MATCH, prepareAllowedMetaFields } = require('./front-matter'); -const DataTypes = require('../types'); -const { preParser } = require('./pre-parser'); -const { processAfterFrontmatterExtracted } = require('./parser-enhancements'); -const { maybeRetrievePartial } = require('./retrieve-partials'); -const { flattenContentOrderedList } = require('./shared-utilities'); -const { ARTICLE_TYPES } = require('./constants'); - -// Just the partial name: /<%=\s+partial\s+partial_version\('([^')]*)'\)[^%>]*%>/ -const parseNanocPartials = (contentString) => - contentString.split(/(<%=\s+partial\s+partial_version\('[^')]*'\)[^%>]*%>)/); - -const removeFalsy = (dataArray) => dataArray.filter((x) => !!x); -const makeTypeFromParentType = (type) => (node) => upperFirst(camelCase(`${node.internal.type}${type}`)); - -const createNodesFromPath = - (type, { createNode, createNodeId, createContentDigest }) => - (path) => { - const pieces = path.split('/'); - const values = { - link: '', - label: '', - level: 0, - }; - const breadcrumbs = pieces.map((piece, i) => { - values.level = values.level + i > 1 ? 1 : values.level + i; - values.link = `${values.link}/${piece}`; - values.label = upperFirst(piece); - values.id = createNodeId(`${values.link} >>> Path`); - - return { ...values }; - }); - breadcrumbs.forEach((breadcrumb, i) => { - const newNodeData = { - ...breadcrumb, - children: [], - }; - if (breadcrumbs[i - 1]) { - newNodeData.parent = breadcrumbs[i - 1].id; - } - const newNodeInternals = { - contentDigest: createContentDigest(breadcrumb.link), - type, - mediaType: 'text/plain', - }; - const pathNode = { - ...newNodeData, - internal: newNodeInternals, - }; - createNode(pathNode); - }); - }; - -const constructDataObjectsFromStrings = (contentStrings, frontmatterMeta) => { - contentStrings = - frontmatterMeta !== NO_MATCH && frontmatterMeta.attributes - ? contentStrings.map((content) => processAfterFrontmatterExtracted(content, frontmatterMeta.attributes)) - : contentStrings; - const dataObjects = contentStrings.map((data, i) => - i % 2 === 0 ? { data: data, type: DataTypes.Html } : { data: data, type: DataTypes.Partial }, - ); - return dataObjects; -}; - -const splitDataAndMetaData = (text) => { - const withPartials = parseNanocPartials(text); - const withoutFalsyValues = removeFalsy(withPartials); - - const frontmatterMeta = tryRetrieveMetaData(withoutFalsyValues[0]); - if (frontmatterMeta !== NO_MATCH) { - withoutFalsyValues[0] = frontmatterMeta.body; - } - - const asDataObjects = constructDataObjectsFromStrings(withoutFalsyValues, frontmatterMeta); - return { - data: asDataObjects, - frontmatterMeta, - }; -}; - -// Source: https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/creating-a-transformer-plugin/ -const transformNanocTextiles = - (node, content, id, type, { createNodesFromPath, createContentDigest, createNodeId }) => - (updateWithTransform) => { - const slug = node.relativePath - .replace(/(.*)\.[^.]+$/, '$1') - .replace('root/', '') - .replace(/index$/, ''); - - // NOTE: we need to exclude all the tutorials pages from the docs site - if (/^tutorials\/.*/.test(slug)) { - return; - } - - const preTextileTransform = preParser(content); - const { data, frontmatterMeta } = splitDataAndMetaData(preTextileTransform); - - let articleType = ARTICLE_TYPES.document; - if (/^api\/.*/.test(slug)) { - articleType = ARTICLE_TYPES.apiReference; - } - - const newNodeData = { - articleType, - contentOrderedList: data, - id, - children: [], - parent: node.id, - }; - - const isVersion = /\/versions\/v[\d.]+/.test(slug); - const isCompare = /^compare\/.*/.test(slug); - const isClientLibDevelopmentGuide = /^client-lib-development-guide\/.*/.test(slug); - - const doesNotNeedMeta = isVersion || isCompare || isClientLibDevelopmentGuide; - - if (frontmatterMeta !== NO_MATCH) { - newNodeData.meta = prepareAllowedMetaFields(filterAllowedMetaFields(frontmatterMeta.attributes)); - if ( - !doesNotNeedMeta && - process.env.NODE_ENV === 'development' && - process.env.EDITOR_WARNINGS_OFF !== 'true' && - !newNodeData.meta.meta_description - ) { - throw new Error( - `No meta_description for file: ${node.relativePath}\n\nPlease add a custom meta_description to the frontmatter YAML at the top of the file.\n\n`, - ); - } - } - - const contentDigest = createContentDigest(data); - - const newNodeInternals = { - contentDigest, - type, - mediaType: 'text/html', - }; - createNodesFromPath(node.relativePath.replace(/\.[^/.]+$/, '')); - newNodeData.slug = slug; - - const htmlNode = { - ...newNodeData, - internal: newNodeInternals, - }; - if (content.id) { - htmlNode.internal[`htmlId`] = content.id; - } - - // Add completely separate nodes to keep track of relevant versions - if (isVersion) { - const version = slug.match(/\/versions\/v([\d.]+)/)[1]; - htmlNode.version = version; - const versionNodeInternals = { - contentDigest, - type: makeTypeFromParentType('Version')(htmlNode), - mediaType: 'text/html', - }; - const versionNodeData = { - parent: id, - id: createNodeId(`${id} >>> Version`), - children: [], - slug, - version, - }; - const versionNode = { - ...versionNodeData, - internal: versionNodeInternals, - }; - updateWithTransform({ parent: htmlNode, child: versionNode }); - } - - updateWithTransform({ parent: node, child: htmlNode }); - }; - -module.exports = { - createNodesFromPath, - transformNanocTextiles, - makeTypeFromParentType, - maybeRetrievePartial, - flattenContentOrderedList, -}; diff --git a/data/transform/parser-enhancements/README.md b/data/transform/parser-enhancements/README.md deleted file mode 100644 index bd0db422ba..0000000000 --- a/data/transform/parser-enhancements/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# Parser Enhancements - -The parser-enhancements directory is intended for use augmenting data before being parsed. - -It is the second stage of the transformation from a _document type_ (e.g. Textile) to a _documentation page_. - -## Compare - -1. [Pre-parser](../pre-parser/README.md) - transforms plain text to plain text ready to be parsed. -2. [Post-parser](../post-parser/README.md) - transforms data after it has been parsed by a dedicated parser such as `textile-js`. -3. [HTML Parser](../../html-parser/README.md) - for HTML manipulations that are too complex for string manipulation or the front-end. -4. Component mapping - maps `{ data, type }` objects to React components based on `type`. -5. React components - standardise the behaviour, presentation, layout and markup semantics of `data` from `{ data, type }` objects. - -## Usage - -It is a good place to put: -* Augmentations based on article meta-data such as document `path`, `frontmatter` attributes -* Augmentations based on application meta-data/config such as `.yaml` files - -It is not the best place to put: -* Transformations designed to fix issues or make the text easier to understand; put these in pre- or post-parser -* Alterations to presentation and design - put these in component mapping or React components \ No newline at end of file diff --git a/data/transform/parser-enhancements/add-dates.js b/data/transform/parser-enhancements/add-dates.js deleted file mode 100644 index d34fcc1a28..0000000000 --- a/data/transform/parser-enhancements/add-dates.js +++ /dev/null @@ -1,10 +0,0 @@ -const addDates = (content, attributes) => { - if (attributes.published_date) { - return content.replace(/(\{\{PUBLISHED_DATE\}\})/gi, attributes.published_date); - } - return content; -}; - -module.exports = { - addDates, -}; diff --git a/data/transform/parser-enhancements/index.js b/data/transform/parser-enhancements/index.js deleted file mode 100644 index c6d3b44d31..0000000000 --- a/data/transform/parser-enhancements/index.js +++ /dev/null @@ -1,14 +0,0 @@ -// textile workarounds removed -const { addDates } = require('./add-dates'); -const { addSpecAnchorLinks } = require('./spec-anchor-links'); - -const processAfterFrontmatterExtracted = (content, attributes = {}, path = null) => { - let result = addSpecAnchorLinks(content, attributes); - result = addDates(result, attributes); - result = addHyphenListSupport(result); - return result; -}; - -module.exports = { - processAfterFrontmatterExtracted, -}; diff --git a/data/transform/parser-enhancements/spec-anchor-links.js b/data/transform/parser-enhancements/spec-anchor-links.js deleted file mode 100644 index f2cc759075..0000000000 --- a/data/transform/parser-enhancements/spec-anchor-links.js +++ /dev/null @@ -1,10 +0,0 @@ -const addSpecAnchorLinks = (content, attributes) => { - if (attributes.anchor_specs) { - return content.replace(/\* @\((\w+)\)@/, "* @($1)@"); - } - return content; -}; - -module.exports = { - addSpecAnchorLinks, -}; diff --git a/data/transform/post-parser/README.md b/data/transform/post-parser/README.md deleted file mode 100644 index 8e878ecb84..0000000000 --- a/data/transform/post-parser/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Post-Parser - -The post-parser directory is intended for use transforming HTML with plain text tokens embedded in it to HTML. - -It is the third stage of the transformation from a _document type_ (e.g. Textile) to a _documentation page_. - -## Compare - -1. [Pre-parser](../pre-parser/README.md) - transforms plain text to plain text ready to be parsed. -2. [Parser enhancements](../parser-enhancements/README.md) - transforms data with enhancements from `attributes` and document `path`. -3. [HTML Parser](../../html-parser/README.md) - for HTML manipulations that are too complex for string manipulation or the front-end. -4. Component mapping - maps `{ data, type }` objects to React components based on `type`. -5. React components - standardise the behaviour, presentation, layout and markup semantics of `data` from `{ data, type }` objects. - -## Usage - -It is a good place to put: -* Operations that cannot take place before the parser runs, for example: - * Operations that rely on text that would be interpreted by the parser as meaningful syntax - * Operations that depend on the specific operations in the pre-parsing stage, such as regex operations on whitespace - * Operations that depend on some HTML to already be present, but cannot be processed through the htmlParser/Cheerio, such as operations on plain text that is not wrapped in HTML but contains some HTML markup. - -It is not the best place to put: -* Operations that remove information for developers only - consider putting these in pre-parser, so there's less text to process later on, and parsing the more complex HTML structure is a little easier. -* Transformations based on frontmatter variables; the frontmatter is extracted after the pre-parser phase, as are partials; partials should inherit frontmatter variables (such as published_date) from their 'parent' page. Consider putting these in parser-enhancements, so that the variables we use are consistently applied & easier to access. -* Final transformations before rendering; consider putting these actions in React components. \ No newline at end of file diff --git a/data/transform/post-parser/blang.test.ts b/data/transform/post-parser/blang.test.ts deleted file mode 100644 index 8310a3234e..0000000000 --- a/data/transform/post-parser/blang.test.ts +++ /dev/null @@ -1,81 +0,0 @@ -import * as fc from 'fast-check'; -import alphaNumericString from '../../../test-generators.js/alphanumeric'; -import { convertBlangBlocksToTokens } from '../pre-parser/language'; -import { brokenBlangExample, brokenBlangTokenExpectedResult } from '../pre-parser/language/blang.raw.examples'; -import { convertBlangBlocksToHtml } from './blang'; - -const createRelevantString = ( - content: string, - { language = 'javascript', isBlang = false, outerTag = false, innerTag = false }, -) => { - // This could be returned by the arrow function directly, but causes havoc with linters! - return `${outerTag ? '

' : ''} - ${isBlang ? `{{LANG_BLOCK[${language}]}}` : ''} - ${innerTag ? '

' : ''}${content}${innerTag ? '
' : ''} - ${isBlang ? '{{/LANG_BLOCK}}' : ''} - ${outerTag ? '

' : ''}`; -}; - -describe('Converts Blang strings to HTML', () => { - // Single checks - it('Leaves single non-blang strings alone', () => { - const nonBlangString = createRelevantString('Lorem ipsum adipiscitor', { - isBlang: false, - outerTag: true, - innerTag: true, - }); - const result = convertBlangBlocksToHtml(nonBlangString); - expect(result).toEqual(nonBlangString); - }); - it('Converts single Blang blocks to HTML', () => { - const blangBlock = createRelevantString('Lorem ipsum adipiscitor', { - isBlang: true, - outerTag: true, - innerTag: true, - }); - const result = convertBlangBlocksToHtml(blangBlock); - expect(result).toBe( - `
-
Lorem ipsum adipiscitor
`, - ); - }); - it('Converts broken Blang block while keeping multiple languages separate', () => { - // cf. data/transform/pre-parser/language/conversions.test.js - const tokenizedBlock = convertBlangBlocksToTokens(brokenBlangExample); - const result = convertBlangBlocksToHtml(tokenizedBlock); - expect(result.replace(/\s+/g, '')).toEqual(brokenBlangTokenExpectedResult.replace(/\s+/g, '')); - }); - - // Fastcheck property testing - it('Never interferes with a non-blang string', () => { - fc.assert( - fc.property(fc.string(), fc.string(), fc.boolean(), fc.boolean(), (content, language, innerTag, outerTag) => { - const nonBlangString = createRelevantString(content, { - isBlang: false, - outerTag, - innerTag, - language, - }); - const result = convertBlangBlocksToHtml(nonBlangString); - expect(result).toEqual(nonBlangString); - }), - ); - }); - it('Always replaces a blang block with HTML', () => { - fc.assert( - fc.property(fc.string(), alphaNumericString, fc.boolean(), (content, language, outerTag) => { - const blangBlock = createRelevantString(content, { - isBlang: true, - outerTag, - innerTag: false, - language, - }); - const result = convertBlangBlocksToHtml(blangBlock); - expect(result).toBe( - `
-${content.trim()}
`, - ); - }), - ); - }); -}); diff --git a/data/transform/post-parser/blang.ts b/data/transform/post-parser/blang.ts deleted file mode 100644 index 65a6f0ca7c..0000000000 --- a/data/transform/post-parser/blang.ts +++ /dev/null @@ -1,24 +0,0 @@ -import { TAG_OPEN_REGEX_STRING, TAG_CLOSE_REGEX_STRING, TAG_OPEN_OR_CLOSE_REGEX_STRINGS } from './constants'; - -/** - * textile-js wraps capital letters in tags, we need to check if those are there - */ -const LANG_BLOCK_POST_TEXTILE_REGEX_STRING = `LANG_(?:)?BLOCK(?:<\\/span>)?`; - -const BLANG_REGEX_STRING = `${ - // Replace the outer tag if any - TAG_OPEN_REGEX_STRING -}{{${ - // The first capturing group, $1 or p1, as in LANG_BLOCK[myText] - LANG_BLOCK_POST_TEXTILE_REGEX_STRING -}\\[([\\w,]+)\\]}}(.*?)${TAG_OPEN_OR_CLOSE_REGEX_STRINGS}{{\\/${LANG_BLOCK_POST_TEXTILE_REGEX_STRING}}}[\\s\\r\\n]*${TAG_CLOSE_REGEX_STRING}`; -const BLANG_REGEX = new RegExp(BLANG_REGEX_STRING, 'gms'); - -export const convertBlangBlocksToHtml: StringTransformation = (content) => { - return content.replace(BLANG_REGEX, (_, p1, p2) => { - return `
\n${p2 - .trim() - // HACK: there is a dangling

tag hanging around, we need to remove it, hence `.replace()` - .replace(/^<\/\s*?p>/, '')}
`; - }); -}; diff --git a/data/transform/post-parser/constants.ts b/data/transform/post-parser/constants.ts deleted file mode 100644 index e84688b027..0000000000 --- a/data/transform/post-parser/constants.ts +++ /dev/null @@ -1,15 +0,0 @@ -// Shared constants between different post-parse operations -/** - * Any number of opening XML tags, inc. HTML tags, followed by any number of spaces - */ -export const TAG_OPEN_REGEX_STRING = '(?:<[\\w ]+>)*[\\s\\r\\n]*'; - -/** - * Any number of closing XML tags, inc. HTML tags, followed by any number of spaces - */ -export const TAG_CLOSE_REGEX_STRING = '(?:)*[\\s\\r\\n]*'; - -/** - * Any number of opening or closing XML tags, inc. HTML tags, or spaces - */ -export const TAG_OPEN_OR_CLOSE_REGEX_STRINGS = '(?:(?:<\\/?[\\w ]+>)*|[\\s\\r\\n]*)'; diff --git a/data/transform/post-parser/index.ts b/data/transform/post-parser/index.ts deleted file mode 100644 index 227e562a4a..0000000000 --- a/data/transform/post-parser/index.ts +++ /dev/null @@ -1,20 +0,0 @@ -import { compose } from 'lodash/fp'; -import { convertBlangBlocksToHtml } from './blang'; -import { rootLevelTextWrapper } from './root-level-text-wrapper'; - -/** - * Added by the pre-parser in order to survive textile parsing - */ -export const addGithubLineBreaks: StringTransformation = (content) => content.replaceAll('{{{github_br}}}', '\n'); - -const LINK_EXTERNAL_REGEX = /(]*)class="external"([^>]*>)/m; - -export const convertExternalLinksToBlankTarget: StringTransformation = (content) => - content.replace(LINK_EXTERNAL_REGEX, '$1target="_blank" rel="noopener noreferrer"$2'); - -export const postParser = compose( - convertExternalLinksToBlankTarget, - convertBlangBlocksToHtml, - addGithubLineBreaks, - rootLevelTextWrapper, -); diff --git a/data/transform/post-parser/root-level-text-wrapper.test.ts b/data/transform/post-parser/root-level-text-wrapper.test.ts deleted file mode 100644 index 489ff1a45c..0000000000 --- a/data/transform/post-parser/root-level-text-wrapper.test.ts +++ /dev/null @@ -1,49 +0,0 @@ -import { rootLevelTextWrapper } from './root-level-text-wrapper'; - -// If this is broken, the line beginning with 'Wherever possible..." will show up -// as only the word 'HATEOS', with no surrounding elements when it is parsed by Cheerio. -const sampleUnwrappedText = `

The properties of an Ably error are:

-
-
code
-
A specific reason code as defined in the public errors definition, where one is known
-
statusCode
-
Where a code is not available, the statusCode provides a generic indication of the nature of the failure and maps to standard HTTP statusCodes
-
message
-
The message string is an English language string that aims to provide useful information to the developer. It is not necessarily intended to be an informative string for the end user
-
-Wherever possible, success response bodies contain links, in HATEOS style, to other resources relevant to the response; where these are present these are included as href attributes on the applicable part of the response object. -

GET, PUT, POST and DELETE are available in all contexts where they make sense. GET is always idempotent.

`; - -const spanInclusiveUnwrappedTextSample = `

{{LANG_BLOCK[default]}}

-

This will instantiate the library using the specified ClientOptions.

-

{{/LANG_BLOCK}}

-

{{LANG_BLOCK[ruby]}}

-

This will instantiate the library and create a new Ably::Rest::Client using the specified ClientOptions.

-

{{/LANG_BLOCK}}
-The REST constructor is used to instantiate the library. The REST library may be instantiated multiple times with the same or different ClientOptions in any given context. Except where specified otherwise, instances operate independently of one another.

`; - -const postTransformUnwrappedTextSample = rootLevelTextWrapper(sampleUnwrappedText); - -const postTransformUnwrappedTextSampleWithSpans = rootLevelTextWrapper(spanInclusiveUnwrappedTextSample); - -it('No section should be left unwrapped by an HTML element at the root level', () => { - expect(postTransformUnwrappedTextSample).toBe(`

The properties of an Ably error are:

-
-
code
-
A specific reason code as defined in the public errors definition, where one is known
-
statusCode
-
Where a code is not available, the statusCode provides a generic indication of the nature of the failure and maps to standard HTTP statusCodes
-
message
-
The message string is an English language string that aims to provide useful information to the developer. It is not necessarily intended to be an informative string for the end user
-
-

Wherever possible, success response bodies contain links, in HATEOS style, to other resources relevant to the response; where these are present these are included as href attributes on the applicable part of the response object.

-

GET, PUT, POST and DELETE are available in all contexts where they make sense. GET is always idempotent.

`); - - expect(postTransformUnwrappedTextSampleWithSpans).toBe(`

{{LANG_BLOCK[default]}}

-

This will instantiate the library using the specified ClientOptions.

-

{{/LANG_BLOCK}}

-

{{LANG_BLOCK[ruby]}}

-

This will instantiate the library and create a new Ably::Rest::Client using the specified ClientOptions.

-

{{/LANG_BLOCK}}
-

The REST constructor is used to instantiate the library. The REST library may be instantiated multiple times with the same or different ClientOptions in any given context. Except where specified otherwise, instances operate independently of one another.

`); -}); diff --git a/data/transform/post-parser/root-level-text-wrapper.ts b/data/transform/post-parser/root-level-text-wrapper.ts deleted file mode 100644 index ade7450b64..0000000000 --- a/data/transform/post-parser/root-level-text-wrapper.ts +++ /dev/null @@ -1,14 +0,0 @@ -/** - * This regex finds: - * (<\/[A-Za-z]+>)\n - closing HTML tag, followed by newline. - * ([A-Z].*)\n - a capital letter preceding any information, up to a newline. - * - * The overall effect is to find capitalised text that immediately follows on - * from a closing tag at the end of a line, which will always be plain text - * that is supposed to be wrapped in

elements but has been missed by the - * textile-js parser. - * - * Regex101: https://regex101.com/r/j4BLqX/1 - */ -const rootLevelTextFinder = /^([A-Z].*)/gm; -export const rootLevelTextWrapper = (content: string) => content.replace(rootLevelTextFinder, '

$1

'); diff --git a/data/transform/pre-parser/README.md b/data/transform/pre-parser/README.md deleted file mode 100644 index 7e7030cb1a..0000000000 --- a/data/transform/pre-parser/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# Pre-Parser - -The pre-parser directory is intended for use transforming plain text to plain text. - -It is the first stage of the transformation from a _document type_ (e.g. Textile) to a _documentation page_. - -For workarounds specific to textile-js such as tokenizing or pre-emptively parsing markup that textile-js gets wrong, see the [textile-js-workarounds](./textile-js-workarounds/README.md) subfolder. - -## Compare - -1. [Parser enhancements](../parser-enhancements/README.md) - transforms data with enhancements from `attributes` and document `path`. -2. [Post-parser](../post-parser/README.md) - transforms data after it has been parsed by a dedicated parser such as `textile-js`. -3. [HTML Parser](../../html-parser/README.md) - for HTML manipulations that are too complex for string manipulation or the front-end. -4. Component mapping - maps `{ data, type }` objects to React components based on `type`. -5. React components - standardise the behaviour, presentation, layout and markup semantics of `data` from `{ data, type }` objects. - -## Usage - -It is a good place to put: -* Regex-based operations that can cheaply transform entire documents -* Operations that remove information for developers only -* Transformations of inline HTML elements that are difficult to implement as their own blocks - -It is not the best place to put: -* Regex-based operations that perform worse on longer documents (e.g. regex operations with a lot of potential backtracking, see: https://blog.stevenlevithan.com/archives/greedy-lazy-performance) - consider putting these in specialised React components, so that they can run on fewer, smaller documents. -* Transformations based on frontmatter variables; the frontmatter is extracted after the pre-parser phase, as are partials; partials should inherit frontmatter variables (such as published_date) from their 'parent' page. Consider putting these in parser-enhancements, so that the variables we use are consistently applied & easier to access. -* Transformations intended to have a very specific output on the front-end; rather than rely on the parser/parser enhancements/component mapping/components to interpret a string change differently, consider implementing these changes later on in the pipeline. - * Replacing data with data from another source; consider putting these in parser-enhancements. - * Broad changes to behaviour, presentation, layout, markup; consider putting these in component-mapping. - * Fine changes to behaviour, presentation, layout, markup; consider putting these in the relevant React components. \ No newline at end of file diff --git a/data/transform/pre-parser/__snapshots__/div-format.test.ts.snap b/data/transform/pre-parser/__snapshots__/div-format.test.ts.snap deleted file mode 100644 index b98fa5bbf1..0000000000 --- a/data/transform/pre-parser/__snapshots__/div-format.test.ts.snap +++ /dev/null @@ -1,830 +0,0 @@ -// Jest Snapshot v1, https://goo.gl/fbAQLP - -exports[`Ensure that divs show up correctly in all cases Ensures that divs show up correctly 6`] = ` -[ -
- - -

- - subscribe(String name, listener( - - Message - - )) - - - void subscribe(String name, - - MessageListener - - listener) - - - void Subscribe(string name, Action< - - Message - - > handler) - - - subscribe(String name) → yields - - Message - - - - subscribe(name: String, callback: ( - - ARTMessage - - ) → Void) -> ARTEventListener? - - - subscribe(name: String, callback: ( - - ARTMessage - - ) → Void) -> ARTEventListener? - - - StreamSubscription< - - ably.Message - - > subscribe(name: String).listen(( - - ably.Message - - ) → void) - -

- - -
, -

- Subscribe to messages with a given event - - name - - on this channel. The caller supplies - - a listener function - - - a lambda expression - - - an implementation of the - - MessageListener - - interface - - - a block - - , which is called each time one or more matching messages arrives on the channel. -

, -
, -
, -
, -
-
-

- - subscribe(String[] names, listener( - - Message - - )) - - - void subscribe(String[] names, - - MessageListener - - listener) - - - subscribe(String *names) → yields - - Message - - - - StreamSubscription< - - ably.Message - - > subscribe(names: List<String>).listen(( - - ably.Message - - ) → void) - -

-
-

- Subscribe a single listener to messages on this channel for multiple event - - name - - values. -

-
, -] -`; - -exports[`Ensure that divs show up correctly in all cases Ensures that divs show up correctly 7`] = ` -[ - { - "attribs": { - "class": "definition", - "id": "subscribe-event", - }, - "data": [ - { - "data": " -", - "name": "text", - "type": "text", - }, - { - "attribs": { - "class": "definition", - }, - "data": [ - { - "attribs": { - "lang": "default", - }, - "data": [ - { - "data": "subscribe(String name, listener(", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "Message", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": "))", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "java", - }, - "data": [ - { - "data": "void subscribe(String name, ", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message-listener", - }, - "data": [ - { - "data": "MessageListener", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": " listener)", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "csharp", - }, - "data": [ - { - "data": "void Subscribe(string name, Action<", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "Message", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": "> handler)", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "ruby", - }, - "data": [ - { - "data": "subscribe(String name) → yields ", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "Message", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "swift", - }, - "data": [ - { - "data": "subscribe(name: String, callback: (", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "ARTMessage", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": ") → Void) -> ARTEventListener?", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "objc", - }, - "data": [ - { - "data": "subscribe(name: String, callback: (", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "ARTMessage", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": ") → Void) -> ARTEventListener?", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "flutter", - }, - "data": [ - { - "data": "StreamSubscription<", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "ably.Message", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": "> subscribe(name: String).listen((", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "ably.Message", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": ") → void)", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - ], - "name": "p", - "type": "tag", - }, - { - "data": " -", - "name": "text", - "type": "text", - }, - ], - "name": "blockquote", - "type": "tag", - }, - { - "attribs": {}, - "data": [ - { - "data": "Subscribe to messages with a given event ", - "name": "text", - "type": "text", - }, - { - "attribs": {}, - "data": [ - { - "data": "name", - "name": "text", - "type": "text", - }, - ], - "name": "code", - "type": "tag", - }, - { - "data": " on this channel. The caller supplies ", - "name": "text", - "type": "text", - }, - { - "attribs": { - "lang": "default", - }, - "data": [ - { - "data": "a listener function", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "csharp", - }, - "data": [ - { - "data": "a lambda expression", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "java", - }, - "data": [ - { - "data": "an implementation of the ", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message-listener", - }, - "data": [ - { - "data": "MessageListener", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": " interface", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "ruby", - }, - "data": [ - { - "data": "a block", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "data": ", which is called each time one or more matching messages arrives on the channel.", - "name": "text", - "type": "text", - }, - ], - "name": "p", - "type": "tag", - }, - { - "attribs": { - "lang": "csharp", - }, - "data": [], - "name": "div", - "type": "tag", - }, - { - "attribs": { - "lang": "swift", - }, - "data": [], - "name": "div", - "type": "tag", - }, - { - "attribs": { - "lang": "objc", - }, - "data": [], - "name": "div", - "type": "tag", - }, - { - "attribs": { - "lang": "default", - }, - "data": [ - { - "attribs": { - "class": "definition", - "id": "subscribe-event-array", - }, - "data": [ - { - "attribs": { - "class": "definition", - }, - "data": [ - { - "attribs": { - "lang": "default", - }, - "data": [ - { - "data": "subscribe(String[] names, listener(", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "Message", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": "))", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "java", - }, - "data": [ - { - "data": "void subscribe(String[] names, ", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message-listener", - }, - "data": [ - { - "data": "MessageListener", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": " listener)", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "ruby", - }, - "data": [ - { - "data": "subscribe(String *names) → yields ", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "Message", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - ], - "name": "span", - "type": "tag", - }, - { - "attribs": { - "lang": "flutter", - }, - "data": [ - { - "data": "StreamSubscription<", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "ably.Message", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": "> subscribe(names: List).listen((", - "name": "text", - "type": "text", - }, - { - "attribs": { - "href": "#message", - }, - "data": [ - { - "data": "ably.Message", - "name": "text", - "type": "text", - }, - ], - "name": "a", - "type": "tag", - }, - { - "data": ") → void)", - "name": "text", - "type": "text", - }, - ], - "name": "span", - "type": "tag", - }, - ], - "name": "p", - "type": "tag", - }, - ], - "name": "blockquote", - "type": "tag", - }, - { - "attribs": {}, - "data": [ - { - "data": "Subscribe a single listener to messages on this channel for multiple event ", - "name": "text", - "type": "text", - }, - { - "attribs": {}, - "data": [ - { - "data": "name", - "name": "text", - "type": "text", - }, - ], - "name": "code", - "type": "tag", - }, - { - "data": " values.", - "name": "text", - "type": "text", - }, - ], - "name": "p", - "type": "tag", - }, - ], - "name": "div", - "type": "tag", - }, -] -`; diff --git a/data/transform/pre-parser/div-format.test.ts b/data/transform/pre-parser/div-format.test.ts deleted file mode 100644 index 9f5cb0788c..0000000000 --- a/data/transform/pre-parser/div-format.test.ts +++ /dev/null @@ -1,132 +0,0 @@ -import { compose } from 'lodash/fp'; -import textile from 'textile-js'; -import { preParser, recursivelyProcessDivs, removeNewlinesBeforeClosingTags } from '.'; -import { fullyParseTextile, processTextile, textileToHtml } from '../../../data/test-utilities/process-textile'; -import { replaceERB } from './erbjs'; -import { - addLanguageSupportForBlockQuotes, - addLanguageSupportForGithubStyleCode, - addLanguageSupportForHeadings, - convertBlangBlocksToTokens, - convertJSAllToNodeAndJavaScript, - duplicateLanguageBlocks, - enforceWhiteSpaceLevelsBetweenLanguageElements, -} from './language'; -import { addMinimizedIndent, addMinimizeForHeadings, stripComments } from './semantic'; -import { textileJSCompatibility } from './textile-js-workarounds'; - -const misbehavingDivFixture = ` - -bq(definition#subscribe-event). - default: subscribe(String name, listener("Message":#message)) - java: void subscribe(String name, "MessageListener":#message-listener listener) - csharp: void Subscribe(string name, Action<"Message":#message> handler) - ruby: subscribe(String name) → yields "Message":#message - objc,swift: subscribe(name: String, callback: ("ARTMessage":#message) -> Void) -> ARTEventListener? - flutter: StreamSubscription<"ably.Message":#message> subscribe(name: String).listen(("ably.Message":#message) -> void) - -Subscribe to messages with a given event @name@ on this channel. The caller supplies a listener functiona lambda expressionan implementation of the "MessageListener":#message-listener interfacea block, which is called each time one or more matching messages arrives on the channel. - -
-
- -bq(definition#subscribe-event-array). - default: subscribe(String[] names, listener("Message":#message)) - java: void subscribe(String[] names, "MessageListener":#message-listener listener) - ruby: subscribe(String *names) → yields "Message":#message - flutter: StreamSubscription<"ably.Message":#message> subscribe(names: List).listen(("ably.Message":#message) -> void) - -Subscribe a single listener to messages on this channel for multiple event @name@ values. -
- -`; - -const processedHtml = processTextile(misbehavingDivFixture); -const cheerioFinal = fullyParseTextile(misbehavingDivFixture); -describe('Ensure that divs show up correctly in all cases', () => { - it('Ensures that divs show up correctly', () => { - expect(recursivelyProcessDivs(misbehavingDivFixture)).toMatchInlineSnapshot(` - " - - bq(definition#subscribe-event). - default: subscribe(String name, listener("Message":#message)) - java: void subscribe(String name, "MessageListener":#message-listener listener) - csharp: void Subscribe(string name, Action<"Message":#message> handler) - ruby: subscribe(String name) → yields "Message":#message - objc,swift: subscribe(name: String, callback: ("ARTMessage":#message) -> Void) -> ARTEventListener? - flutter: StreamSubscription<"ably.Message":#message> subscribe(name: String).listen(("ably.Message":#message) -> void) - - Subscribe to messages with a given event @name@ on this channel. The caller supplies a listener functiona lambda expressionan implementation of the "MessageListener":#message-listener interfacea block, which is called each time one or more matching messages arrives on the channel. - -
-

subscribe(String[] names, listener(Message))void subscribe(String[] names, MessageListener listener)subscribe(String *names) → yields MessageStreamSubscription<ably.Message> subscribe(names: List<String>).listen((ably.Message) → void)

Subscribe a single listener to messages on this channel for multiple event name values.

 - - " - `); - const partialPreParser = compose( - // Textile compatibility must follow all other changes - textileJSCompatibility, - recursivelyProcessDivs, - // Language operations - addLanguageSupportForHeadings, - addLanguageSupportForBlockQuotes, - enforceWhiteSpaceLevelsBetweenLanguageElements, - duplicateLanguageBlocks, - addLanguageSupportForGithubStyleCode, - convertBlangBlocksToTokens, - convertJSAllToNodeAndJavaScript, - // Readability/Semantic operations - addMinimizedIndent, - addMinimizeForHeadings, - stripComments, - removeNewlinesBeforeClosingTags, - // ERB to JS - replaceERB, - ); - - expect(partialPreParser(misbehavingDivFixture)).toMatchInlineSnapshot(` - " - - bq(definition#subscribe-event). subscribe(String name, listener(Message))void subscribe(String name, MessageListener listener)void Subscribe(string name, Action<Message> handler)subscribe(String name) → yields Messagesubscribe(name: String, callback: (ARTMessage) -> Void) -> ARTEventListener?StreamSubscription<ably.Message> subscribe(name: String).listen((ably.Message) -> void) - - - Subscribe to messages with a given event name on this channel. The caller supplies a listener functiona lambda expressionan implementation of the MessageListener interfacea block, which is called each time one or more matching messages arrives on the channel. - -
-

subscribe(String[] names, listener(Message))void subscribe(String[] names, MessageListener listener)subscribe(String *names) → yields MessageStreamSubscription<ably.Message> subscribe(names: List<String>).listen((ably.Message) → void)

Subscribe a single listener to messages on this channel for multiple event name values.

 - - " - `); - expect(preParser(misbehavingDivFixture)).toMatchInlineSnapshot(` - " - - bq(definition#subscribe-event). subscribe(String name, listener(Message))void subscribe(String name, MessageListener listener)void Subscribe(string name, Action<Message> handler)subscribe(String name) → yields Messagesubscribe(name: String, callback: (ARTMessage) -> Void) -> ARTEventListener?StreamSubscription<ably.Message> subscribe(name: String).listen((ably.Message) -> void) - - - Subscribe to messages with a given event name on this channel. The caller supplies a listener functiona lambda expressionan implementation of the MessageListener interfacea block, which is called each time one or more matching messages arrives on the channel. - -
-

subscribe(String[] names, listener(Message))void subscribe(String[] names, MessageListener listener)subscribe(String *names) → yields MessageStreamSubscription<ably.Message> subscribe(names: List<String>).listen((ably.Message) → void)

Subscribe a single listener to messages on this channel for multiple event name values.

 - - " - `); - expect(textile(preParser(misbehavingDivFixture))).toMatchInlineSnapshot(` - "
-

subscribe(String name, listener(Message))void subscribe(String name, MessageListener listener)void Subscribe(string name, Action<Message> handler)subscribe(String name) → yields Messagesubscribe(name: String, callback: (ARTMessage) → Void) -> ARTEventListener?StreamSubscription<ably.Message> subscribe(name: String).listen((ably.Message) → void)

-
-

Subscribe to messages with a given event name on this channel. The caller supplies a listener functiona lambda expressionan implementation of the MessageListener interfacea block, which is called each time one or more matching messages arrives on the channel.

-
-

subscribe(String[] names, listener(Message))void subscribe(String[] names, MessageListener listener)subscribe(String *names) → yields MessageStreamSubscription<ably.Message> subscribe(names: List<String>).listen((ably.Message) → void)

Subscribe a single listener to messages on this channel for multiple event name values.

" - `); - expect(textileToHtml(misbehavingDivFixture)).toMatchInlineSnapshot(` - "
-

subscribe(String name, listener(Message))void subscribe(String name, MessageListener listener)void Subscribe(string name, Action<Message> handler)subscribe(String name) → yields Messagesubscribe(name: String, callback: (ARTMessage) → Void) -> ARTEventListener?StreamSubscription<ably.Message> subscribe(name: String).listen((ably.Message) → void)

-
-

Subscribe to messages with a given event name on this channel. The caller supplies a listener functiona lambda expressionan implementation of the MessageListener interfacea block, which is called each time one or more matching messages arrives on the channel.

-
-

subscribe(String[] names, listener(Message))void subscribe(String[] names, MessageListener listener)subscribe(String *names) → yields MessageStreamSubscription<ably.Message> subscribe(names: List<String>).listen((ably.Message) → void)

Subscribe a single listener to messages on this channel for multiple event name values.

" - `); - expect(processedHtml).toMatchSnapshot(); - expect(cheerioFinal).toMatchSnapshot(); - }); -}); diff --git a/data/transform/pre-parser/erbjs/README.md b/data/transform/pre-parser/erbjs/README.md deleted file mode 100644 index f29a167731..0000000000 --- a/data/transform/pre-parser/erbjs/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# ERB in JS - -This is a section of the app that manages a very limited subset of ERB functionality. - -The ERB-JS folder will not transpile Ruby code or render arbitrary code. - -It recognises & works with only very specific strings: - -1. ```<%= JsBins.url_for('${quote}') %>``` -2. ```<%= Ably::DOCUMENTATION_LANGUAGES.map { |lang_id, lang| "@#{lang_id}@" }.join(', ') %>``` -3. ```<% @items.select { |d| d[:section] == '${design-patterns|tutorials}' }.sort_by { |d| d[:title] }.each do |item| %>\n"<%= html_escape(item[:title]) %>":<%= html_escape(item.path) %><% end %>``` -4. ```<% ['👦', ${...emojis}].each do |emoji| %><% end %>``` - -## Alternatives - -If a need comes up for proper ERB support in the future, here are some options that were considered but caused too many delays in the initial implementation: - -1. Parsing out tokens and registering JavaScript functionality to them manually -1. Transpiling the Ruby snippets using Opal's opal-parser.js library - -The reason these are complicated are because: - -1. Parsing out tokens: - 1. Parsing out tokens requires keeping track of scope - 2. Requires a small DSL to manage the tokens in between JS and Ruby -2. Transpiling snippets directly: - 1. ERB can still be nested, so some level of recursive interpretation is necessary - 2. Many of the dependent variables are implicitly available because of Rails' magic, so they are not easy to access without transpiling all the Ruby & Rails code. diff --git a/data/transform/pre-parser/erbjs/emoji.test.js b/data/transform/pre-parser/erbjs/emoji.test.js deleted file mode 100644 index ce00b08b33..0000000000 --- a/data/transform/pre-parser/erbjs/emoji.test.js +++ /dev/null @@ -1,25 +0,0 @@ -const { emojiReplacer } = require('./emojis'); - -describe('Makes sure that the emoji type of ERB is correctly replaced', () => { - it('replaces an ERB attempting to render emoji with specific HTML', () => { - const sampleText = `

- Avatar: - <% ['👦', '👧', '👨', '👩', '😺'].each do |emoji| %> - - <% end %> -

- -`; - const expectedResult = `

- Avatar: - - - - - -

- -`; - expect(emojiReplacer(sampleText)).toBe(expectedResult); - }); -}); diff --git a/data/transform/pre-parser/erbjs/emojis.js b/data/transform/pre-parser/erbjs/emojis.js deleted file mode 100644 index 6fa81460c6..0000000000 --- a/data/transform/pre-parser/erbjs/emojis.js +++ /dev/null @@ -1,19 +0,0 @@ -const emojiRegex = - /<% \[(.*?)\]\.each do \|emoji\| %>\s*
outside the
but it isn't clever enough to manage that) - */ -const trimWhitespaceBetweenSpans = (content) => - content.replace(/<\/span>\s+/g, ''); - -const ensureNewlineBetweenDivs = (content) => - content.replace(/<\/div>\s*/g, '
\n
'); - -const enforceWhiteSpaceLevelsBetweenLanguageElements = (content) => { - return trimWhitespaceBetweenSpans(ensureNewlineBetweenDivs(content)); -}; - -module.exports = { - enforceWhiteSpaceLevelsBetweenLanguageElements, -}; diff --git a/data/transform/pre-parser/semantic/index.js b/data/transform/pre-parser/semantic/index.js deleted file mode 100644 index 98a6397ce8..0000000000 --- a/data/transform/pre-parser/semantic/index.js +++ /dev/null @@ -1,9 +0,0 @@ -const { addMinimizeForHeadings, addMinimizedIndent } = require('./minimize'); - -const stripComments = content => content.replace(/\s*/g, ''); - -module.exports = { - stripComments, - addMinimizedIndent, - addMinimizeForHeadings -} \ No newline at end of file diff --git a/data/transform/pre-parser/semantic/minimize.js b/data/transform/pre-parser/semantic/minimize.js deleted file mode 100644 index aba33a365c..0000000000 --- a/data/transform/pre-parser/semantic/minimize.js +++ /dev/null @@ -1,48 +0,0 @@ -const { extractIndented } = require('../shared-utilities/extract-indented'); - -const MINIMIZE_REGEX = /^minimize\.(.*)[\r\n]/m; -const MINIMIZED_HEADINGS_REGEX = /^(h[1-6])(\(#[^)]+\))?\(minimize(?:=([^)]*))?\)\.(.*?)\n\n(.+?)(?=(?:\n\nh[1-6]))/gm; -const VIEW_MORE_TEXT = 'View More'; - -const getDetailsComponentAsString = (title, body) => - `
${title}
${body}
\n`; - -const addMinimizeForHeadings = (content) => { - const replacer = (_match, hTag, anchor, expandTitle, title, innerContent) => { - const fullExpandTitle = expandTitle ?? VIEW_MORE_TEXT; - return `${hTag}${anchor}.${title}\n\n` + getDetailsComponentAsString(fullExpandTitle, innerContent); - }; - return content.replace(MINIMIZED_HEADINGS_REGEX, replacer); -}; - -const getAllContentAfterRegex = (content, position) => { - const nextContent = content.slice(position); // get content after regex - return nextContent.replace(MINIMIZE_REGEX, '').slice(1); -}; - -const addMinimizedIndent = (content) => { - let position = content.search(MINIMIZE_REGEX); - while (position > -1) { - const minimizeTitle = content.match(MINIMIZE_REGEX)[0].trim(); - const matchTitle = minimizeTitle === 'minimize.' ? VIEW_MORE_TEXT : minimizeTitle.replace('minimize.', ''); - - // Only indented lines are part of the hidden panel - const { onlyIndentedLines, nonIndentedLineLocation } = extractIndented( - getAllContentAfterRegex(content, position), - 'minimize.', - ); - - content = - content.substring(0, position) + - getDetailsComponentAsString(matchTitle.trim(), onlyIndentedLines) + - content.substring(position + content.match(MINIMIZE_REGEX)[0].length + nonIndentedLineLocation); - position = content.search(MINIMIZE_REGEX); - } - - return content; -}; - -module.exports = { - addMinimizeForHeadings, - addMinimizedIndent, -}; diff --git a/data/transform/pre-parser/semantic/minimize.test.js b/data/transform/pre-parser/semantic/minimize.test.js deleted file mode 100644 index a64ac59e41..0000000000 --- a/data/transform/pre-parser/semantic/minimize.test.js +++ /dev/null @@ -1,68 +0,0 @@ -const { addMinimizeForHeadings, addMinimizedIndent } = require("./minimize"); - -const h3Minimize = `h3(#minimizable-title)(minimize=Click to see how to minimize by title). Minimize on the title - -Some content - -h3. Next title`; -const h3MinimizeNoTitle = `h3(#minimizable-title)(minimize). Minimize on the title - -Some content no title - -h3. Next title`; -const h3MinimizeExpected = `h3(#minimizable-title). Minimize on the title - -
Click to see how to minimize by title
Some content
- - -h3. Next title`; -const h3MinimizeExpectedViewMore = `h3(#minimizable-title). Minimize on the title - -
View More
Some content no title
- - -h3. Next title`; - -describe('Adds minimize tokens for headings with (minimize)d content', () => { - - it('Successfully adds minimize tokens as wrappers for headings in format h3(minimize).', () => { - const result = addMinimizeForHeadings(h3Minimize); - expect(result).toEqual(h3MinimizeExpected); - }); - - it('Successfully adds minimize tokens as wrappers for headings in format h3(minimize) with no title.', () => { - const result = addMinimizeForHeadings(h3MinimizeNoTitle); - expect(result).toEqual(h3MinimizeExpectedViewMore); - }); -}); - -const sectionMinimize = `minimize. Click to see how to minimize by block - It is also possible to create a minimizable section with the *minimize. [Optional minimizable text]* line, with any following indented lines being included in the minimizable section. If no optional minimize button text is typed, it will default to *View More*. - -h3. Next title`; -const sectionMinimizeNoTitle = `minimize. - It is also possible to create a minimizable section with the *minimize. [Optional minimizable text]* line, with any following indented lines being included in the minimizable section. If no optional minimize button text is typed, it will default to *View More*. - -h3. Next title`; -const sectionMinimizeExpected = `
Click to see how to minimize by block
It is also possible to create a minimizable section with the *minimize. [Optional minimizable text]* line, with any following indented lines being included in the minimizable section. If no optional minimize button text is typed, it will default to *View More*. -
- - -h3. Next title`; -const sectionMinimizeExpectedNoTitle = `
View More
It is also possible to create a minimizable section with the *minimize. [Optional minimizable text]* line, with any following indented lines being included in the minimizable section. If no optional minimize button text is typed, it will default to *View More*. -
- - -h3. Next title`; - -describe('Adds minimize tokens for sections with minimize.d content', () => { - it('Successfully adds minimize tokens as wrappers for sections marked with minimize. and indentations', () => { - const result = addMinimizedIndent(sectionMinimize); - expect(result).toEqual(sectionMinimizeExpected); - }); - it('Successfully adds minimize tokens as wrappers for sections marked with minimize. (with no title) and indentations', () => { - const result = addMinimizedIndent(sectionMinimizeNoTitle); - expect(result).toEqual(sectionMinimizeExpectedNoTitle); - }); -}) - diff --git a/data/transform/pre-parser/shared-utilities/extract-indented.ts b/data/transform/pre-parser/shared-utilities/extract-indented.ts deleted file mode 100644 index 6f0fa3a967..0000000000 --- a/data/transform/pre-parser/shared-utilities/extract-indented.ts +++ /dev/null @@ -1,41 +0,0 @@ -const INDENTATION_REGEX = /^(\s+).*$/m; - -export const extractIndented = (text: string, name = 'Indentable', allowEmptyLines = false) => { - /** - * Find some amount of indentation followed by some amount of content - */ - const indentationResult = text.match(INDENTATION_REGEX); - if (!indentationResult || !indentationResult[1]) { - throw `${name} blocks must be followed by indentation. Offending block: '${text.slice(0, 127)}'\n`; - } - - const indentation = indentationResult[1]; - /** - * Find the same level of indentation we matched first in the text - */ - const indentationRegexString = `^${indentation}(.*)$`; - const indentationRegex = new RegExp(indentationRegexString, 'gm'); - /** - * Find the next instance that doesn't match the same level of indentation we matched in the text - * - * If allowEmptyLines is truthy, find the next instance that doesn't match the same level of indentation - * we matched in the text AND isn't an empty line. - */ - const negativeIndentationRegexString = allowEmptyLines - ? `^(?!${indentation}.*\\n)(?!\\s*\\n)` - : `^(?!${indentation}.*)$`; - const negativeIndentationRegex = new RegExp(negativeIndentationRegexString, 'gm'); - - const nonIndentedLineLocation = text.search(negativeIndentationRegex); - - /** - * If we can't find a non-indented line, that's likely an error in the regex; display this at build time - */ - if (nonIndentedLineLocation === -1) { - throw `${name} block regex error, could not find ${negativeIndentationRegex.source} in ${text.slice(0, 100)}`; - } - - const onlyIndentedLines = text.slice(0, nonIndentedLineLocation).replace(indentationRegex, '$1'); - - return { onlyIndentedLines, nonIndentedLineLocation }; -}; diff --git a/data/transform/pre-parser/textile-js-workarounds/README.md b/data/transform/pre-parser/textile-js-workarounds/README.md deleted file mode 100644 index 9d3368ffff..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Textile Workarounds - -This folder is for functions that _only_ exist to workaround limitations of textile-js, or differences between textile-js and the Ruby implementation(s) of textile parsers. - -Some other workarounds exist elsewhere in the codebase, for example in [white-space.js](../language/white-space.js). These will be commented separately. - -All tests relating to ensuring the quirks of textile-js are accounted for are included here, please feel free to move them if you feel they would be more appropriate elsewhere. - -`workarounds.raw.examples.js` contains useful examples that might throw up problematic HTML when parsed by textile. \ No newline at end of file diff --git a/data/transform/pre-parser/textile-js-workarounds/add-bold-text.test.ts b/data/transform/pre-parser/textile-js-workarounds/add-bold-text.test.ts deleted file mode 100644 index 2902e567d2..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/add-bold-text.test.ts +++ /dev/null @@ -1,15 +0,0 @@ -import { default as fc } from 'fast-check'; -import { addBoldText } from './add-bold-text'; - -const stringWithoutAsterisks = fc.string().map((s) => s.replaceAll('*', '')); - -describe('Textile bold text is replaced correctly with a element', () => { - it('Wraps textile bold text in a element', () => { - expect(addBoldText(`**Type: String**`)).toBe(`Type: String`); - }); - it('Wraps any text that has no asterisks in a element', () => { - fc.assert( - fc.property(stringWithoutAsterisks, (a) => expect(addBoldText(`**${a}**`)).toBe(`${a}`)), - ); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/add-bold-text.ts b/data/transform/pre-parser/textile-js-workarounds/add-bold-text.ts deleted file mode 100644 index 923d910950..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/add-bold-text.ts +++ /dev/null @@ -1,3 +0,0 @@ -// textile-js has difficulty adding bolded text in certain circumstances, particularly near (but not wrapped in!) elements. -// NB: this is not just a textile workaround. -export const addBoldText = (content: string): string => content.replace(/\*\*(.*?)\*\*/gm, '$1'); diff --git a/data/transform/pre-parser/textile-js-workarounds/add-hyphen-list-support.test.ts b/data/transform/pre-parser/textile-js-workarounds/add-hyphen-list-support.test.ts deleted file mode 100644 index 92a0f6f31b..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/add-hyphen-list-support.test.ts +++ /dev/null @@ -1,41 +0,0 @@ -import { addHyphenListSupport } from './add-hyphen-list-support'; - -describe('Add support for hyphen-led lists in textile-js', () => { - it('Replaces hyphens followed by at least one space with asterisks followed by at least one space', () => { - expect( - addHyphenListSupport( - `- Item one -- Item two -- Item three`, - ), - ).toBe(`* Item one -* Item two -* Item three`); - }); - it('Replaces hyphens in a real world example', () => { - expect( - addHyphenListSupport( - `- *Active traffic management*: Let Ably actively monitor not only the global cluster health but also your own endpoints and proactively take steps to isolate or move traffic to ensure business continuity. -- *Dedicated, isolated clusters*: Rely upon guaranteed capacity and isolation from noisy neighbors. -- *Regional routing of traffic*: Require that all traffic is routed and serviced within specific regions. -- *Regional message storage*: Require that all messages are stored within a specific region.`, - ), - ) - .toBe(`* *Active traffic management*: Let Ably actively monitor not only the global cluster health but also your own endpoints and proactively take steps to isolate or move traffic to ensure business continuity. -* *Dedicated, isolated clusters*: Rely upon guaranteed capacity and isolation from noisy neighbors. -* *Regional routing of traffic*: Require that all traffic is routed and serviced within specific regions. -* *Regional message storage*: Require that all messages are stored within a specific region.`); - }); - it('Does not affect definition lists', () => { - expect( - addHyphenListSupport(`- *Active traffic management*:= Let Ably actively monitor not only the global cluster health but also your own endpoints and proactively take steps to isolate or move traffic to ensure business continuity. -- *Dedicated, isolated clusters*:= Rely upon guaranteed capacity and isolation from noisy neighbors. -- *Regional routing of traffic*:= Require that all traffic is routed and serviced within specific regions. -- *Regional message storage*:= Require that all messages are stored within a specific region.`), - ) - .toBe(`- *Active traffic management*:= Let Ably actively monitor not only the global cluster health but also your own endpoints and proactively take steps to isolate or move traffic to ensure business continuity. -- *Dedicated, isolated clusters*:= Rely upon guaranteed capacity and isolation from noisy neighbors. -- *Regional routing of traffic*:= Require that all traffic is routed and serviced within specific regions. -- *Regional message storage*:= Require that all messages are stored within a specific region.`); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/add-hyphen-list-support.ts b/data/transform/pre-parser/textile-js-workarounds/add-hyphen-list-support.ts deleted file mode 100644 index 998efa75c9..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/add-hyphen-list-support.ts +++ /dev/null @@ -1,4 +0,0 @@ -/** - * Textile JS does not support hyphen-led unordered lists - */ -export const addHyphenListSupport: StringTransformation = (content) => content.replace(/^- (?!.*:=)(.*)$/gm, '* $1'); diff --git a/data/transform/pre-parser/textile-js-workarounds/add-italicised-text.test.ts b/data/transform/pre-parser/textile-js-workarounds/add-italicised-text.test.ts deleted file mode 100644 index bea2842365..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/add-italicised-text.test.ts +++ /dev/null @@ -1,7 +0,0 @@ -import { addItalicisedText } from './add-italicised-text'; - -describe('Textile italicised text is replaced correctly with an block', () => { - it('Wraps textile italicised text in an block', () => { - expect(addItalicisedText(`__Type: String__`)).toBe(`Type: String`); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/add-italicised-text.ts b/data/transform/pre-parser/textile-js-workarounds/add-italicised-text.ts deleted file mode 100644 index 8106f4e300..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/add-italicised-text.ts +++ /dev/null @@ -1,4 +0,0 @@ -// textile-js has difficulty adding italicised text in certain circumstances, particularly near (but not wrapped in!) elements. -// NB: this is not just a textile workaround. -export const addItalicisedText: StringTransformation = (content) => - content.replace(/__(.*?)__/gm, '$1'); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-html-tags-with-newlines.ts b/data/transform/pre-parser/textile-js-workarounds/fix-html-tags-with-newlines.ts deleted file mode 100644 index 0e826cf3d3..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-html-tags-with-newlines.ts +++ /dev/null @@ -1,3 +0,0 @@ -// Restrict this for img tags for now; we do not know what the implications of a larger-scale replacement would be. -export const fixImgTagsWithNewlines: StringTransformation = (content) => - content.replace(/]*\n+[^>]*>/g, (match) => match.replace(/\s{2,}/gm, ' ')); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-inline-code.test.ts b/data/transform/pre-parser/textile-js-workarounds/fix-inline-code.test.ts deleted file mode 100644 index fba9b54216..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-inline-code.test.ts +++ /dev/null @@ -1,13 +0,0 @@ -import { fixInlineCode } from './fix-inline-code'; - -describe('Fixes inline code for textile-js', () => { - it('Correctly fixes inline code', () => { - expect( - fixInlineCode( - `* If the connection state becomes @SUSPENDED@, all previously-@ATTACHED@ or @ATTACHING@ channels will become @SUSPENDED@`, - ), - ).toBe( - `* If the connection state becomes SUSPENDED, all previously-ATTACHED or ATTACHING channels will become SUSPENDED`, - ); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-inline-code.ts b/data/transform/pre-parser/textile-js-workarounds/fix-inline-code.ts deleted file mode 100644 index f279a9716d..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-inline-code.ts +++ /dev/null @@ -1,3 +0,0 @@ -// textile-js, unlike RedCloth, does not interpret @...@ sections as elements -// if they are preceded by a non-space character -export const fixInlineCode: StringTransformation = (content) => content.replace(/@(.+?)@/gm, '$1'); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-leading-html-tags.test.ts b/data/transform/pre-parser/textile-js-workarounds/fix-leading-html-tags.test.ts deleted file mode 100644 index 55cee0e4bd..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-leading-html-tags.test.ts +++ /dev/null @@ -1,9 +0,0 @@ -import { fixLeadingHtmlTags } from './fix-leading-html-tags'; - -describe('Fixes leading inline HTML tags by replacing them with paragraph wrappers ahead of time.', () => { - it('Ensures bold HTML tags are supplmented by being wrapped in paragraph tags', () => { - expect(fixLeadingHtmlTags('*Note*: Lorem ipsum API content API')).toBe( - '

*Note*: Lorem ipsum API content API

', - ); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-leading-html-tags.ts b/data/transform/pre-parser/textile-js-workarounds/fix-leading-html-tags.ts deleted file mode 100644 index aaf7df357a..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-leading-html-tags.ts +++ /dev/null @@ -1,7 +0,0 @@ -/** - * This function fixes issues where textile would see an inline text tag as the first - * thing that it sees in a paragraph, and avoid wrapping that paragraph tag correctly in - *

tags - * We achieve this by doing the wrapping ahead of time. - */ -export const fixLeadingHtmlTags: StringTransformation = (content) => content.replace(/^(\*[^\s]+\*.*)$/gm, '

$1

'); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-links.test.ts b/data/transform/pre-parser/textile-js-workarounds/fix-links.test.ts deleted file mode 100644 index 61a91a696c..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-links.test.ts +++ /dev/null @@ -1,155 +0,0 @@ -import textile from 'textile-js'; -import { fixDuplicateQuoteLinks, fixHtmlElementsInLinks, fixPunctuationInLinks } from './fix-links'; - -describe('Fixes duplicate quoted links for textile-js', () => { - it('Correctly renders links with long gaps between quotes', () => { - expect( - textile( - fixDuplicateQuoteLinks( - `The @Channel@ object can also emit one event that is not a state change: an @update@ event. This happens when there's a change to channel conditions for which the channel state doesn't change. For example, a partial loss of message continuity on a channel (typically after a resume) for which the channel state remains @attached@ would lead to an @update@ event being emitted, with both @current@ and @previous@ set to "@attached@". and the @resumed@ flag set to @false@. So if you get such an event, you'll know there may be messages you've missed on the channel, and if necessary you can use the "History":#history api to retrieve them.`, - ), - ), - ).toBe( - `

The Channel object can also emit one event that is not a state change: an update event. This happens when there’s a change to channel conditions for which the channel state doesn’t change. For example, a partial loss of message continuity on a channel (typically after a resume) for which the channel state remains attached would lead to an update event being emitted, with both current and previous set to attached and the resumed flag set to false. So if you get such an event, you’ll know there may be messages you’ve missed on the channel, and if necessary you can use the History api to retrieve them.

`, - ); - }); -}); - -describe('Does not render bits of code as links', () => { - it('ignores bits of code when it comes to parsing links', () => { - /** - * The broken example would look like this: - * "x-ably-capability": "{\*\"*\"]}" - * Ticket: https://ably.atlassian.net/browse/EDU-1319 - **/ - expect( - fixHtmlElementsInLinks(` - var claims = { - "iat": currentTime, /* current time in seconds */ - "exp": currentTime + 3600, /* time of expiration in seconds */ - "x-ably-capability": "{\\"*\\":[\\"*\\"]}" - } - `), - ).toBe(` - var claims = { - "iat": currentTime, /* current time in seconds */ - "exp": currentTime + 3600, /* time of expiration in seconds */ - "x-ably-capability": "{\\"*\\":[\\"*\\"]}" - } - `); - expect( - fixPunctuationInLinks(` - var claims = { - "iat": currentTime, /* current time in seconds */ - "exp": currentTime + 3600, /* time of expiration in seconds */ - "x-ably-capability": "{\\"*\\":[\\"*\\"]}" - } - `), - ).toBe(` - var claims = { - "iat": currentTime, /* current time in seconds */ - "exp": currentTime + 3600, /* time of expiration in seconds */ - "x-ably-capability": "{\\"*\\":[\\"*\\"]}" - } - `); - }); -}); - -describe('Fixes punctuation in links for textile-js', () => { - it('Deliberately renders links followed by punctuation so as to remove punctuation from the link', () => { - expect( - fixPunctuationInLinks(`yes ("basic":/rest-api/#basic-authentication or "token":/rest-api#token-authentication)`), - ).toBe( - `yes (basic or token)`, - ); - expect( - fixPunctuationInLinks( - `Ably Token issued will be "anonymous":https://faqs.ably.com/authenticated-and-identified-clients.
__Type: @Boolean@__`, - ), - ).toBe( - `Ably Token issued will be anonymous.
__Type: @Boolean@__`, - ); - expect( - fixPunctuationInLinks( - `h5. Code example - - \`\`\`[curl] - curl "https://rest.ably.io/event-stream?channel=example&v=1.2" \ - --user "{{API_KEY}}" - - { - "id":"cbfKayrzgAXDWM:1556804156735-0", - "event":"message", - "data":{ - "id":"oZs6XaGYx8:0:0", - "name":"message-name", - "timestamp":1556804156730, - "encoding":"json", - "channel":"example", - "data":"{"foo":1}" - } - } - ⏎ - { - "event":"error", - "data":{ - "message":"Token expired. (See https://help.ably.io/error/40142 for help.)", - "code":40142, - "statusCode":401, - "href":"https://help.ably.io/error/40142" - } - } - \`\`\``, - ), - ).toMatchInlineSnapshot(` - "h5. Code example - - \`\`\`[curl] - curl "https://rest.ably.io/event-stream?channel=example&v=1.2" --user "{{API_KEY}}" - - { - "id":"cbfKayrzgAXDWM:1556804156735-0", - "event":"message", - "data":{ - "id":"oZs6XaGYx8:0:0", - "name":"message-name", - "timestamp":1556804156730, - "encoding":"json", - "channel":"example", - "data":"{"foo":1}" - } - } - ⏎ - { - "event":"error", - "data":{ - "message":"Token expired. (See https://help.ably.io/error/40142 for help.)", - "code":40142, - "statusCode":401, - "href":"https://help.ably.io/error/40142" - } - } - \`\`\`" - `); - }); - - it('Renders links with multiple punctuation marks correctly', () => { - expect(fixPunctuationInLinks(`subscribe(String name, listener("Message":#message))`)).toBe( - `subscribe(String name, listener(Message))`, - ); - }); -}); - -describe('Fixes HTML elements in links for textile-js', () => { - it('Correctly renders links with HTML elements in the URL portion', () => { - expect( - textile( - fixHtmlElementsInLinks( - `"Lorem ipsum":lorem-ipsum-ad-loquitur"Alternative Lorem Ipsum":per-ardua-ad-astra`, - ), - ), - ).toBe( - `

Lorem ipsumAlternative Lorem Ipsum

`, - ); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-links.ts b/data/transform/pre-parser/textile-js-workarounds/fix-links.ts deleted file mode 100644 index 9a86c4e7c7..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-links.ts +++ /dev/null @@ -1,28 +0,0 @@ -// Duplicate quote links are gathered GREEDILY, not LAZILY by textile-js when a code section is nested inside quotes. -// The issue here is that the quotes are essentially duplicating the work of the 'code' element, marking out the -// contents as a discrete & specific entity, but textile-js scans all the way until it can find a colon and -// force the element to be an -export const fixDuplicateQuoteLinks: StringTransformation = (content) => content.replace(/"(@[^"]*@)"[^:]/g, '$1'); - -/** - * The regex in this comment block is used throughout to identify valid link content. - * To avoid errors when parsing code, the heuristic that the link text must contain at - * least one printable character, not including underscore, has been relied upon. - * [^">] => identifies non-quote and non-angle-bracket characters - * [a-zA-Z0-9] => identifies alphanumeric characters - * "([^">]*[a-zA-Z0-9]+[^">]*)" => identifies valid link text - * - * \w has been deliberately avoided because '_', which \w includes, could be part of code. - */ - -// HTML elements immediately after links cause difficulties for the parser, appearing in links. -export const fixHtmlElementsInLinks: StringTransformation = (content) => - content.replace(/"([^">]*[a-zA-Z0-9]+[^">]*)":([^)\]@,\s<>"]+)$1<'); - -// Punctuation immediately after links is interpreted correctly by textile-js; but was not by Nanoc. -// We need to remove it to retain parity. -export const fixPunctuationInLinks: StringTransformation = (content) => - content.replace( - /"([^">]*[a-zA-Z0-9]+[^">]*)":([^)\]@,\s<>\d{}}"]+?)(\.?)([)\]@,\s<>{}"])/gm, - '$1$3$4', - ); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-divs-in-definition-lists.ts b/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-divs-in-definition-lists.ts deleted file mode 100644 index b58a86bd29..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-divs-in-definition-lists.ts +++ /dev/null @@ -1,41 +0,0 @@ -import { isEmpty } from 'lodash'; - -/** - * Breakdown; - * 1st capturing group; ensure we are part of a textile definition list - * - preceded by a line of - dt := dd followed by any number of spaces - * - OR part of an ongoing chain indicated by a closing tag followed by a newline. - * non-capturing group: a
with a lang attribute, closed by a
pair, if it exists - * non-capturing group: :=\s - * 4th capturing group: the second section of a textile
pair, if it exists - * Next div, that matches the exact same pattern as above - */ -const DIV_DL_REGEX = - /(-.*?:=.*?\n\n)(?:(?:]*lang="([^"]+?)")[^>]*>(?:[\n\r]+- ([^:=]*? ))?(?::=\s+)?(.*?)<\/div>\s*(?:(?:]*lang="([^"]+?)")[^>]*>(?:[\n\r]+- ([^:=]*? ))?(?::=\s+)?(.*?)<\/div>/gs; - -/** - * Identify sequence of one or more divs within dl sequence - * To be altered, the div must have a lang attribute. - * If a div with a lang attribute is empty, it is an alternative div in a definition list. It must be replaced with actual textile markup. - * If a div with a lang attribute has no second portion, it is the end of the definition list; it must be left unchanged. - * If a div has both a first & second portion, it can be adjusted to. - */ -export const fixDivsInDefinitionLists: StringTransformation = (content) => - content.replace( - DIV_DL_REGEX, - (match, textilePreamble, lang, maybeFirstDt, maybeFirstDd, secondLang, maybeSecondDt, maybeSecondDd) => { - if (isEmpty(lang) || isEmpty(secondLang)) { - return match; - } - const firstEntry = isEmpty(maybeFirstDt) - ? `-
:= ` - : `-
${maybeFirstDt.replace(/^-/g, '').trim()}
:= ${maybeFirstDd}`; - const secondEntry = isEmpty(maybeSecondDt) - ? `-
:= ` - : `-
${maybeSecondDt.replace(/^-/g, '').trim()}
:= ${maybeSecondDd}`; - return `${textilePreamble}${firstEntry} -${secondEntry}`; - }, - ); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-h1-6-after-definition-lists.ts b/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-h1-6-after-definition-lists.ts deleted file mode 100644 index 24ea0b8b51..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-h1-6-after-definition-lists.ts +++ /dev/null @@ -1,2 +0,0 @@ -export const fixH1To6AFterDefinitionLists: StringTransformation = (content) => - content.replace(/(\n-(.*?):=(.*?)\n)(h[1-6])/g, '$1\n$2'); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-indented-definition-lists.ts b/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-indented-definition-lists.ts deleted file mode 100644 index 92ae111123..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-indented-definition-lists.ts +++ /dev/null @@ -1,2 +0,0 @@ -export const fixIndentedDefinitionLists: StringTransformation = (content) => - content.replace(/^[^\S\n]+(-.*?:=.*)$/gm, '$1'); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-newlines-in-definition-lists.ts b/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-newlines-in-definition-lists.ts deleted file mode 100644 index 0826b34412..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-newlines-in-definition-lists.ts +++ /dev/null @@ -1,3 +0,0 @@ -const NEWLINE_DL_REGEX = /(-.*?:=.*?)[\n\r]{2,}(-.*?:=.*?)/g; - -export const fixNewlinesInDefinitionLists = (content: string) => content.replace(NEWLINE_DL_REGEX, '$1\n$2'); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-textile-definition-lists.test.ts b/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-textile-definition-lists.test.ts deleted file mode 100644 index 4c887a82d3..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/fix-textile-definition-lists.test.ts +++ /dev/null @@ -1,27 +0,0 @@ -import { fixDivsInDefinitionLists } from './fix-divs-in-definition-lists'; -import { failingDefinitionList } from './test-data'; - -describe('Definition lists are interpreted as intended', () => { - it('transforms
s in
s into
pairs', () => { - /** - * Potential issues uncovered by test: - * Problem: - * divs are included separately from
lists, i.e.
term := definition
- * Solution: - * ensure divs are processed when part of a
- */ - expect(fixDivsInDefinitionLists(failingDefinitionList)).toBe(`h4. Parameters - -- name := The event name to subscribe to
__Type: @String@__ - --
:= --
names
:= An argument array of event names to subscribe to
__Type: @String[]@ @*argument@__ - - --
listener
:= is a function of the form @function(message)@ to be called for each message --
"MessageListener":#message-listener listener
:= Message listener to be notified for matching messages --
&block
:= yields each matching message when received on the channel --
callback
:= called with each matching "@message@":#message when received on the channel --
handler
:= called with each matching "@message@":#message when received on the channel`); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/index.ts b/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/index.ts deleted file mode 100644 index 84148bd2fe..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/index.ts +++ /dev/null @@ -1,10 +0,0 @@ -import { compose } from 'lodash/fp'; -import { fixH1To6AFterDefinitionLists } from './fix-h1-6-after-definition-lists'; -import { fixIndentedDefinitionLists } from './fix-indented-definition-lists'; -import { fixNewlinesInDefinitionLists } from './fix-newlines-in-definition-lists'; - -export const fixTextileDefinitionLists = compose( - fixH1To6AFterDefinitionLists, - fixNewlinesInDefinitionLists, - fixIndentedDefinitionLists, -); diff --git a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/test-data.ts b/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/test-data.ts deleted file mode 100644 index 19ededc819..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/fix-textile-definition-lists/test-data.ts +++ /dev/null @@ -1,14 +0,0 @@ -export const failingDefinitionList = `h4. Parameters - -- name := The event name to subscribe to
__Type: @String@__ - -
-
-- names := An argument array of event names to subscribe to
__Type: @String[]@ @*argument@__ -
- --
listener
:= is a function of the form @function(message)@ to be called for each message --
"MessageListener":#message-listener listener
:= Message listener to be notified for matching messages --
&block
:= yields each matching message when received on the channel --
callback
:= called with each matching "@message@":#message when received on the channel --
handler
:= called with each matching "@message@":#message when received on the channel`; diff --git a/data/transform/pre-parser/textile-js-workarounds/heading.test.ts b/data/transform/pre-parser/textile-js-workarounds/heading.test.ts deleted file mode 100644 index 01dd77b00d..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/heading.test.ts +++ /dev/null @@ -1,458 +0,0 @@ -import { processTextile } from '../../../../data/test-utilities/process-textile'; -import textile from 'textile-js'; -import { preParser } from '..'; - -describe('Manual override of headings works as expected', () => { - it('Manually overrides headings when there are classes and IDs and definition lists involved', () => { - expect( - textile( - preParser(`h5. Request parameters - -- channels := **mandatory**. One or more channel names, separated by commas (or the @separator@ if specified). Non-url-safe characters should be URL-encoded (for example, @?channels=foo%3Fbar@ will subscribe to the channel @foo?bar@). Alias: @channel@. -- v := **mandatory**. The version of the api you are requesting. The current version of the API is 1.2, so @v=1.2@ is recommended. -- separator := **optional**. A separator, to enable easy subscriptions to channels with commas in their name. For example, @?separator=|&channel=fo,o|ba,r@ will subscribe to the two channels @fo,o@ and @ba,r@. -- key := **optional**. An Ably API key to use, if using basic auth. -- accessToken := **optional** An Ably auth token to use, if using token auth. -- lastEvent := **optional**. An @id@ to resume from. Only required when starting a new SSE connection which resumes from a previous connection. -- rewind := **optional**. An integer which, if specified, will send a backlog of the number of messages specified once the connection opens. For example, @rewind=1@ will give you the most recent message sent on the channel. This is best-effort — only messages from within the last two minutes will be available, and only if the channel has been continuously active since the message was sent; it is not a replacement for the "history API":/rest/history. It only has an effect for new connections; when resuming a previous connection using @lastEvent@, it is ignored in favour of sending you the messages you missed since you were last connected. -- enveloped := **optional**. Default is @true@. If @true@, the @data@ from each event envelope for a @message@ event will be a "Message":/api/realtime-sdk/types#message object. If @false@, it will be the payload from the message directly. See "Envelope format":#envelope-format below. -- heartbeats := **optional**. Default is @false@. if @true@ will use an explicit heartbeat event rather than a newline as a keepalive packet. - -h5(#envelope-format). Envelope format - -See an example of a "plain event stream":#event-stream below, except instead of a JSON object with @id@, @event@, @data@ members, you get an SSE event. - -Keepalive packets are sent as SSE comments (@:keepalive@).`), - ), - ).toBe(`

Request parameters

-
-\t
channels
-\t
mandatory. One or more channel names, separated by commas (or the separator if specified). Non-url-safe characters should be URL-encoded (for example, ?channels=foo%3Fbar will subscribe to the channel foo?bar). Alias: channel.
-\t
v
-\t
mandatory. The version of the api you are requesting. The current version of the API is 1.2, so v=1.2 is recommended.
-\t
separator
-\t
optional. A separator, to enable easy subscriptions to channels with commas in their name. For example, ?separator=|&channel=fo,o|ba,r will subscribe to the two channels fo,o and ba,r.
-\t
key
-\t
optional. An Ably API key to use, if using basic auth.
-\t
accessToken
-\t
optional An Ably auth token to use, if using token auth.
-\t
lastEvent
-\t
optional. An id to resume from. Only required when starting a new SSE connection which resumes from a previous connection.
-\t
rewind
-\t
optional. An integer which, if specified, will send a backlog of the number of messages specified once the connection opens. For example, rewind=1 will give you the most recent message sent on the channel. This is best-effort — only messages from within the last two minutes will be available, and only if the channel has been continuously active since the message was sent; it is not a replacement for the history API. It only has an effect for new connections; when resuming a previous connection using lastEvent, it is ignored in favour of sending you the messages you missed since you were last connected.
-\t
enveloped
-\t
optional. Default is true. If true, the data from each event envelope for a message event will be a Message object. If false, it will be the payload from the message directly. See Envelope format below.
-\t
heartbeats
-\t
optional. Default is false. if true will use an explicit heartbeat event rather than a newline as a keepalive packet.
-
-
Envelope format
-

See an example of a plain event stream below, except instead of a JSON object with id, event, data members, you get an SSE event.

-

Keepalive packets are sent as SSE comments (:keepalive).

`); - }); - it('Works for duplicated h[1-6] blocks as well', () => { - expect( - processTextile(`h4. Parameters - --
event(s)
:= the connection event(s) to subscribe to
__Type: @String@ or @String[]@__ --
event
:= the connection event to subscribe to
__Type: "@ConnectionEvent@":#connection-event__ --
event
:= the connection event to subscribe to
__Type: "@ConnectionEvent@":#connection-event__ --
event
:= the connection event as a Symbol such as @:connected@ or @ConnectionEvent@ object to subscribe to
__Type: "@ConnectionEvent@":#connection-event__ --
event
:= the connection event to subscribe to
__Type: "@ARTRealtimeConnectionEvent@":#connection-event__ - --
listener
:= is a function of the form @function(stateChange)@ to be notified for a single occurrence of a matching event --
listener
:= listener to be notified for a single occurrence of a matching state change
__Type: "@ConnectionStateListener@":#connection-state-listener__ --
action
:= action to be executed for matching state changes
__Type: "@ConnectionStateChange@":#connection-state-listener__ --
&block
:= listener block that is yielded to for a single occurrence of a matching event --
call
:= called with matching events -h6(#off). - default: off - csharp: Off - -There are sixtwo overloaded versions of this method:`), - ).toMatchInlineSnapshot(` - [ -

- Parameters -

, -
- - -
-
-
- event(s) -
-
-
- the connection event(s) to subscribe to -
- - Type: - - String - - or - - String[] - - -
-
-
-
-
- event(s) -
-
-
- the connection event(s) to subscribe to -
- - Type: - - String - - or - - String[] - - -
-
- - - - -
-
-
- event -
-
-
- the connection event to subscribe to -
- - Type: - - - ConnectionEvent - - - -
-
- - - - -
-
-
- event -
-
-
- the connection event to subscribe to -
- - Type: - - - ConnectionEvent - - - -
-
- - - - -
-
-
- event -
-
-
- the connection event as a Symbol such as - - :connected - - or - - ConnectionEvent - - object to subscribe to -
- - Type: - - - ConnectionEvent - - - -
-
- - - - -
-
-
- event -
-
-
- the connection event to subscribe to -
- - Type: - - - ARTRealtimeConnectionEvent - - - -
-
-
-
-
- event -
-
-
- the connection event to subscribe to -
- - Type: - - - ARTRealtimeConnectionEvent - - - -
-
- - - - -
-
-
- listener -
-
-
- is a function of the form - - function(stateChange) - - to be notified for a single occurrence of a matching event -
-
-
-
-
- listener -
-
-
- is a function of the form - - function(stateChange) - - to be notified for a single occurrence of a matching event -
-
- - - - -
-
-
- listener -
-
-
- listener to be notified for a single occurrence of a matching state change -
- - Type: - - - ConnectionStateListener - - - -
-
- - - - -
-
-
- action -
-
-
- action to be executed for matching state changes -
- - Type: - - - ConnectionStateChange - - - -
-
- - - - -
-
-
- &block -
-
-
- listener block that is yielded to for a single occurrence of a matching event -
-
- - - - -
-
-
- call -
-
-
- called with matching events -
-
-
-
-
- call -
-
-
- called with matching events -
-
- - - - -
, -
- - off - - - Off - -
, -

- There are - - six - - - six - - - two - - overloaded versions of this method: -

, - ] - `); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/index.test.ts b/data/transform/pre-parser/textile-js-workarounds/index.test.ts deleted file mode 100644 index 9bdf2cf7d4..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/index.test.ts +++ /dev/null @@ -1,43 +0,0 @@ -import textile from 'textile-js'; -import { compressMultipleNewlinesInLists, manuallyReplaceHTags } from './'; -import { - definitionList, - expectedDefinitionList, - nestedH1_6String, - nestedH1_6Html, - nestedDiv, - spanWithHashExample, - spanWithHashResult, - listDivExample, - listDivParsedExample, -} from './workarounds.raw.examples'; -import { preParser } from '../'; - -describe('Reads a definition string correctly', () => { - it('A definition string is rendered into a valid HTML definition list from textile', () => { - expect(textile(compressMultipleNewlinesInLists(definitionList)).replace(/\s/g, '')).toEqual( - expectedDefinitionList.replace(/\s/g, ''), - ); - }); -}); - -describe('Reads an h[1-6]. string correctly', () => { - it('An h[1-6]. line nested inside an outer HTML tag gets read correctly in textile', () => { - expect(textile(manuallyReplaceHTags(nestedH1_6String))).toEqual(nestedH1_6Html); - }); -}); - -describe('Reads spans with hashes correctly', () => { - it('A span with a hash/pound/octothorpe value gets read correctly', () => { - const processedSpan = textile(preParser(spanWithHashExample)); - expect(processedSpan).toEqual(spanWithHashResult); - }); -}); - -describe('Reads divs closing over a definition list correctly', () => { - it('A series of one or more divs followed by another div gets parsed correctly', () => { - const preParsedDivs = preParser(listDivExample); - const processedDivs = textile(preParsedDivs); - expect(processedDivs.replace(/\s/g, '')).toEqual(listDivParsedExample.replace(/\s/g, '')); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/index.ts b/data/transform/pre-parser/textile-js-workarounds/index.ts deleted file mode 100644 index df3a2412a5..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/index.ts +++ /dev/null @@ -1,37 +0,0 @@ -import { compose } from 'lodash/fp'; -import { fixDuplicateQuoteLinks, fixHtmlElementsInLinks, fixPunctuationInLinks } from './fix-links'; -import { fixInlineCode } from './fix-inline-code'; -import { fixTextileDefinitionLists } from './fix-textile-definition-lists'; -import { addItalicisedText } from './add-italicised-text'; -import { fixLeadingHtmlTags } from './fix-leading-html-tags'; -import { addBoldText } from './add-bold-text'; -import { makeImplicitOrderedListExplicit } from './make-implicit-ordered-list-explicit'; -import { fixImgTagsWithNewlines } from './fix-html-tags-with-newlines'; - -// textile-js, unlike RedCloth, cannot parse multiple new lines between list items -// each list item will instead be wrapped in its own list collection -export const compressMultipleNewlinesInLists: StringTransformation = (content) => - content.replace(/^(-.*)\n{2,}(?![^-])/gm, '$1\n'); - -// textile-js cannot parse h[1-6]. lines that are located inside another HTML tag, with leading spaces -export const manuallyReplaceHTags: StringTransformation = (content) => - content.replace( - /^\s*h([1-6])(\(#[^)]+\))?(\([^()|#)]+\))?\.\s+(.*)$/gm, - (_match, p1, p2, p3, p4) => - `\n${p4}`, - ); - -export const textileJSCompatibility = compose( - fixLeadingHtmlTags, - fixTextileDefinitionLists, - fixInlineCode, - compressMultipleNewlinesInLists, - makeImplicitOrderedListExplicit, - manuallyReplaceHTags, - fixImgTagsWithNewlines, - fixDuplicateQuoteLinks, - fixPunctuationInLinks, - fixHtmlElementsInLinks, - addItalicisedText, - addBoldText, -); diff --git a/data/transform/pre-parser/textile-js-workarounds/make-implicit-ordered-list-explicit.test.ts b/data/transform/pre-parser/textile-js-workarounds/make-implicit-ordered-list-explicit.test.ts deleted file mode 100644 index 06bcb3b88d..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/make-implicit-ordered-list-explicit.test.ts +++ /dev/null @@ -1,40 +0,0 @@ -import textile from 'textile-js'; -import { preParser } from '..'; -import { postParser } from '../../post-parser'; -import { makeImplicitOrderedListExplicit } from './make-implicit-ordered-list-explicit'; - -describe('Ensure that implicit ordered lists (decimal-led lines) are converted to explicit Textile ordered lists', () => { - it('Interprets ordered lists correctly', () => { - expect( - makeImplicitOrderedListExplicit(` - -Ably supports two methods of authentication: - -1. "Basic authentication":/core-features/authentication#basic-authentication -2. "Token authentication":/core-features/authentication#token-authentication`), - ).toBe(` - -Ably supports two methods of authentication: - -# "Basic authentication":/core-features/authentication#basic-authentication -# "Token authentication":/core-features/authentication#token-authentication`); - }); - it('Preserves ordered lists throughout the parsing process', () => { - expect( - postParser( - textile( - preParser(` - -Ably supports two methods of authentication: - -1. "Basic authentication":/core-features/authentication#basic-authentication -2. "Token authentication":/core-features/authentication#token-authentication`), - ), - ), - ).toBe(`

Ably supports two methods of authentication:

-
    -
  1. Basic authentication
    2. -
  2. Token authentication
    3. -
`); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/make-implicit-ordered-list-explicit.ts b/data/transform/pre-parser/textile-js-workarounds/make-implicit-ordered-list-explicit.ts deleted file mode 100644 index def5a319f9..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/make-implicit-ordered-list-explicit.ts +++ /dev/null @@ -1,4 +0,0 @@ -// Not supporting implicit OLs at different indentation levels because the -// chance of causing unexpected behaviour is too high. -export const makeImplicitOrderedListExplicit: StringTransformation = (content) => - content.replace(/^\d+\.(.+)$/gm, '# $1'); diff --git a/data/transform/pre-parser/textile-js-workarounds/missing-spans.test.ts b/data/transform/pre-parser/textile-js-workarounds/missing-spans.test.ts deleted file mode 100644 index f9f565a214..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/missing-spans.test.ts +++ /dev/null @@ -1,1292 +0,0 @@ -import { processTextile } from '../../../test-utilities/process-textile'; - -// Source: _request.textile -const missingSpansFixture = `h4. Parameters - -- method := either @get@, @post@, @put@, @patch@ or @delete@.
__Type: Stringstring__ -- path := the path to query.
__Type: Stringstring__ -- params := (optional) any querystring parameters needed.
__Type: ObjectPaginateParamsDictionary__ -- body := (optional; for @post@, @put@ and @patch@ methods) the body of the request, as anything that can be serialized into JSON, such as an @Object@ or @Array@.a JToken.
__Type: SerializableinterfaceJToken__ -- headers := (optional) any headers needed. If provided, these will be mixed in with the default library headers.
__Type: Objecthttp.HeaderDictionary__ - -blang[jsall,objc,swift]. - h4. Callback result - - On successfully receiving a response from Ably, @results@ contains an "@HttpPaginatedResponse@@ARTHttpPaginatedResponse@":/api/rest-sdk/types#http-paginated-response containing the @statusCode@ of the response, a @success@ boolean (equivalent to whether the status code is between 200 and 299), @headers@, and an @items@ array containing the current page of results. It supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods, identically to "@PaginatedResult@":/api/rest-sdk/types#paginated-result. - - On failure to obtain a response, @err@ contains an "@ErrorInfo@":/api/rest-sdk/types#error-info object with an error response as defined in the "Ably REST API":/rest-api#common documentation. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an @err@). - -blang[java,ruby,php,python]. - h4. Returns - - On successfully receiving a response from Ably, the returned "@HttpPaginatedResponse@":/api/rest-sdk/types#http-paginated-response contains a @status_code@@statusCode@ and a @success@ boolean, @headers@, and an @items@ array containing the current page of results. It supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods, identically to "@PaginatedResult@":/api/rest-sdk/types#paginated-result. - - Failure to obtain a response will raise an "@AblyException@":/api/realtime-sdk/types#ably-exception. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an exception). - -blang[csharp]. - h4. Returns - - The method is asynchronous and return a Task that has to be awaited to get the result. - - On successfully receiving a response from Ably, the returned "@HttpPaginatedResponse@":/api/rest-sdk/types#http-paginated-response containing the @StatusCode@ and a @Success@ boolean, @Headers@, and an @Items@ array containing the current page of results. "@HttpPaginatedResponse@":/api/rest-sdk/types#http-paginated-response supports pagination using "@NextAsync@":#paginated-result and "@FirstAsync@":#paginated-result methods. - - Failure to obtain a response will raise an "@AblyException@":/api/realtime-sdk/types#ably-exception. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an exception). -`; - -describe('Ensure that there are no missing spans', () => { - it('Ensures that there are no missing spans for any language', () => { - expect(processTextile(missingSpansFixture)).toMatchInlineSnapshot(` - [ -

- Parameters -

, -
- - -
- method -
- - -
- either - - get - - , - - post - - , - - put - - , - - patch - - or - - delete - - . -
- - Type: - - String - - - string - - - string - - -
- - -
- path -
- - -
- the path to query. -
- - Type: - - String - - - string - - - string - - -
- - -
- params -
- - -
- (optional) any querystring parameters needed. -
- - Type: - - Object - - - PaginateParams - - - Dictionary<string, string> - - -
- - -
- body -
- - -
- (optional; for - - post - - , - - put - - and - - patch - - methods) the body of the request, as - - anything that can be serialized into - - JSON - - , such as an - - Object - - or - - Array - - . - - - a JToken. - -
- - Type: - - Serializable - - - interface - - - JToken - - -
- - -
- headers -
- - -
- (optional) any headers needed. If provided, these will be mixed in with the default library headers. -
- - Type: - - Object - - - http.Header - - - Dictionary<string, string> - - -
- - -
, -
- - - - -

-

- Callback result -

-

- - -

- On successfully receiving a response from Ably, - - results - - contains an - - - - HttpPaginatedResponse - - - - - ARTHttpPaginatedResponse - - - - - ARTHttpPaginatedResponse - - - - containing the - - statusCode - - of the response, a - - success - - boolean (equivalent to whether the status code is between 200 and 299), - - headers - - , and an - - items - - array containing the current page of results. It supports pagination using - - - next - - - and - - - first - - - methods, identically to - - - PaginatedResult - - - . -

- - -

- On failure to obtain a response, - - err - - contains an - - - ErrorInfo - - - object with an error response as defined in the - - Ably - - REST - - - - API - - - documentation. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an - - HTTP - - Paginated Response, not an - - err - - ). -

-
, -
- - - - -

-

- Callback result -

-

- - -

- On successfully receiving a response from Ably, - - results - - contains an - - - - HttpPaginatedResponse - - - - - ARTHttpPaginatedResponse - - - - - ARTHttpPaginatedResponse - - - - containing the - - statusCode - - of the response, a - - success - - boolean (equivalent to whether the status code is between 200 and 299), - - headers - - , and an - - items - - array containing the current page of results. It supports pagination using - - - next - - - and - - - first - - - methods, identically to - - - PaginatedResult - - - . -

- - -

- On failure to obtain a response, - - err - - contains an - - - ErrorInfo - - - object with an error response as defined in the - - Ably - - REST - - - - API - - - documentation. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an - - HTTP - - Paginated Response, not an - - err - - ). -

-
, -
- - - - -

-

- Callback result -

-

- - -

- On successfully receiving a response from Ably, - - results - - contains an - - - - HttpPaginatedResponse - - - - - ARTHttpPaginatedResponse - - - - - ARTHttpPaginatedResponse - - - - containing the - - statusCode - - of the response, a - - success - - boolean (equivalent to whether the status code is between 200 and 299), - - headers - - , and an - - items - - array containing the current page of results. It supports pagination using - - - next - - - and - - - first - - - methods, identically to - - - PaginatedResult - - - . -

- - -

- On failure to obtain a response, - - err - - contains an - - - ErrorInfo - - - object with an error response as defined in the - - Ably - - REST - - - - API - - - documentation. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an - - HTTP - - Paginated Response, not an - - err - - ). -

-
, -
- - - - -

-

- Callback result -

-

- - -

- On successfully receiving a response from Ably, - - results - - contains an - - - - HttpPaginatedResponse - - - - - ARTHttpPaginatedResponse - - - - - ARTHttpPaginatedResponse - - - - containing the - - statusCode - - of the response, a - - success - - boolean (equivalent to whether the status code is between 200 and 299), - - headers - - , and an - - items - - array containing the current page of results. It supports pagination using - - - next - - - and - - - first - - - methods, identically to - - - PaginatedResult - - - . -

- - -

- On failure to obtain a response, - - err - - contains an - - - ErrorInfo - - - object with an error response as defined in the - - Ably - - REST - - - - API - - - documentation. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an - - HTTP - - Paginated Response, not an - - err - - ). -

-
, -
- - - - -

-

- Returns -

-

- - -

- On successfully receiving a response from Ably, the returned - - - HttpPaginatedResponse - - - contains a - - - status_code - - - - - status_code - - - - - statusCode - - - and a - - success - - boolean, - - headers - - , and an - - items - - array containing the current page of results. It supports pagination using - - - next - - - and - - - first - - - methods, identically to - - - PaginatedResult - - - . -

- - -

- Failure to obtain a response will raise an - - - AblyException - - - . (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an - - HTTP - - Paginated Response, not an exception). -

-
, -
- - - - -

-

- Returns -

-

- - -

- On successfully receiving a response from Ably, the returned - - - HttpPaginatedResponse - - - contains a - - - status_code - - - - - status_code - - - - - statusCode - - - and a - - success - - boolean, - - headers - - , and an - - items - - array containing the current page of results. It supports pagination using - - - next - - - and - - - first - - - methods, identically to - - - PaginatedResult - - - . -

- - -

- Failure to obtain a response will raise an - - - AblyException - - - . (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an - - HTTP - - Paginated Response, not an exception). -

-
, -
- - - - -

-

- Returns -

-

- - -

- On successfully receiving a response from Ably, the returned - - - HttpPaginatedResponse - - - contains a - - - status_code - - - - - status_code - - - - - statusCode - - - and a - - success - - boolean, - - headers - - , and an - - items - - array containing the current page of results. It supports pagination using - - - next - - - and - - - first - - - methods, identically to - - - PaginatedResult - - - . -

- - -

- Failure to obtain a response will raise an - - - AblyException - - - . (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an - - HTTP - - Paginated Response, not an exception). -

-
, -
- - - - -

-

- Returns -

-

- - -

- On successfully receiving a response from Ably, the returned - - - HttpPaginatedResponse - - - contains a - - - status_code - - - - - status_code - - - - - statusCode - - - and a - - success - - boolean, - - headers - - , and an - - items - - array containing the current page of results. It supports pagination using - - - next - - - and - - - first - - - methods, identically to - - - PaginatedResult - - - . -

- - -

- Failure to obtain a response will raise an - - - AblyException - - - . (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an - - HTTP - - Paginated Response, not an exception). -

-
, -
- - - - -

-

- Returns -

-

- - -

- The method is asynchronous and return a Task that has to be awaited to get the result. -

- - -

- On successfully receiving a response from Ably, the returned - - - HttpPaginatedResponse - - - containing the - - StatusCode - - and a - - Success - - boolean, - - Headers - - , and an - - Items - - array containing the current page of results. - - - HttpPaginatedResponse - - - supports pagination using - - - NextAsync - - - and - - - FirstAsync - - - methods. -

- - -

- Failure to obtain a response will raise an - - - AblyException - - - . (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an - - HTTP - - Paginated Response, not an exception). -
-

-
, - ] - `); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/recursively-process-divs.test.ts b/data/transform/pre-parser/textile-js-workarounds/recursively-process-divs.test.ts deleted file mode 100644 index 3a81b2b376..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/recursively-process-divs.test.ts +++ /dev/null @@ -1,18 +0,0 @@ -import { recursivelyProcessDivs } from '..'; - -describe('Divs that contain examples of textile to be processed correctly', () => { - it('Renders a known example from api/realtime-sdk/channels.textile correctly', () => { - expect( - recursivelyProcessDivs(` -
-bq(definition#on-state-array-listener). - jsall: on(String[] events, listener("ChannelStateChange":#channel-state-change stateChange)) - -Same as above, but registers multiple listeners, one for each event in the array. -
`), - ).toMatchInlineSnapshot(` - " -

on(String[] events, listener(ChannelStateChange stateChange))

Same as above, but registers multiple listeners, one for each event in the array.

" - `); - }); -}); diff --git a/data/transform/pre-parser/textile-js-workarounds/workarounds.raw.examples.ts b/data/transform/pre-parser/textile-js-workarounds/workarounds.raw.examples.ts deleted file mode 100644 index 4f8abe4df9..0000000000 --- a/data/transform/pre-parser/textile-js-workarounds/workarounds.raw.examples.ts +++ /dev/null @@ -1,150 +0,0 @@ -export const definitionList = `h3(#connection-states). Available connection states - -A series of connection states is defined as follows: - -- initialized := A @Connection@ object having this state has been initialized but no connection has yet been attempted. - -- connecting := A connection attempt has been initiated. The connecting state is entered as soon as the library has completed initialization, and is reentered each time connection is re-attempted following disconnection. - -- connected := A connection exists and is active. - -- disconnected := A temporary failure condition. No current connection exists because there is no network connectivity or no host is available.

The disconnected state is entered if an established connection is dropped, or if a connection attempt was unsuccessful. In the disconnected state the library will periodically attempt to open a new connection (approximately every 15 seconds), anticipating that the connection will be re-established soon and thus connection and channel continuity will be possible.

In this state, developers can continue to publish messages as they are automatically placed in a local queue, to be sent as soon as a connection is reestablished. Messages published by other clients whilst this client is disconnected will be delivered to it upon reconnection, so long as the connection was resumed within 2 minutes.

After 2 minutes have elapsed, recovery is no longer possible and the connection will move to the @suspended@ state. - -- suspended := A long term failure condition. No current connection exists because there is no network connectivity or no host is available.

The suspended state is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended state, the library will periodically attempt to open a new connection every 30 seconds. Developers are unable to publish messages in this state. A new connection attempt can also be triggered by an explicit call to "@connect()@@connect@@Connect()@:#connect":#connect on the @Connection@ object.

Once the connection has been re-established, channels will be automatically re-attached. The client has been disconnected for too long for them to resume from where they left off, so if it wants to catch up on messages published by other clients while it was disconnected, it needs to use the "history API":/realtime/history. - -- closing := An explicit request by the developer to close the connection has been sent to the Ably service. If a reply is not received from Ably within a short period of time, the connection will be forcibly terminated and the connection state will become @closed@. - -- closed := The connection has been explicitly closed by the client.

In the closed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. No connection state is preserved by the service or by the library. A new connection attempt can be triggered by an explicit call to "@connect()@@connect@@Connect()@:#connect":#connect on the @Connection@ object, which will result in a new connection. - -- failed := This state is entered if the client library encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service (e.g. an attempt to connect with an incorrect API key), or some local terminal error (e.g. the token in use has expired and the library does not have any way to renew it).

In the failed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. A new connection attempt can be triggered by an explicit call to "@connect()@@connect@@Connect()@:#connect":#connect on the @Connection@ object. -`; - -export const expectedDefinitionList = `

Available connection states

-

A series of connection states is defined as follows:

-
-
initialized
-
A Connection object having this state has been initialized but no connection has yet been attempted.
-
connecting
-
A connection attempt has been initiated. The connecting state is entered as soon as the library has completed initialization, and is reentered each time connection is re-attempted following disconnection.
-
connected
-
A connection exists and is active.
-
disconnected
-
A temporary failure condition. No current connection exists because there is no network connectivity or no host is available.

The disconnected state is entered if an established connection is dropped, or if a connection attempt was unsuccessful. In the disconnected state the library will periodically attempt to open a new connection (approximately every 15 seconds), anticipating that the connection will be re-established soon and thus connection and channel continuity will be possible.

In this state, developers can continue to publish messages as they are automatically placed in a local queue, to be sent as soon as a connection is reestablished. Messages published by other clients whilst this client is disconnected will be delivered to it upon reconnection, so long as the connection was resumed within 2 minutes.

After 2 minutes have elapsed, recovery is no longer possible and the connection will move to the suspended state.
-
suspended
-
A long term failure condition. No current connection exists because there is no network connectivity or no host is available.

The suspended state is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended state, the library will periodically attempt to open a new connection every 30 seconds. Developers are unable to publish messages in this state. A new connection attempt can also be triggered by an explicit call to connect()connectConnect():#connect on the Connection object.

Once the connection has been re-established, channels will be automatically re-attached. The client has been disconnected for too long for them to resume from where they left off, so if it wants to catch up on messages published by other clients while it was disconnected, it needs to use the history API.
-
closing
-
An explicit request by the developer to close the connection has been sent to the Ably service. If a reply is not received from Ably within a short period of time, the connection will be forcibly terminated and the connection state will become closed.
-
closed
-
The connection has been explicitly closed by the client.

In the closed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. No connection state is preserved by the service or by the library. A new connection attempt can be triggered by an explicit call to connect()connectConnect():#connect on the Connection object, which will result in a new connection.
-
failed
-
This state is entered if the client library encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service (e.g. an attempt to connect with an incorrect API key), or some local terminal error (e.g. the token in use has expired and the library does not have any way to renew it).

In the failed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. A new connection attempt can be triggered by an explicit call to connect()connectConnect():#connect on the Connection object.
-
`; - -export const nestedH1_6String = `
- h1. Lorem ipsum -vos populi vos dei -calamitus calamitabandum -
`; - -export const nestedH1_6Html = `

Lorem ipsum

-vos populi vos dei -calamitus calamitabandum -
`; - -export const nestedDiv = `h6(#unsubscribe). - default: unsubscribe - csharp: Unsubscribe - -
-There are sixthree overloaded versions of this method: -
- -bq(definition#unsubscribe-event). -default: unsubscribe(String name, listener) -java: void unsubscribe(String name, "MessageListener":#message-listener listener) -csharp: bool Unsubscribe(string eventName, Action<"Message":#message> handler) -ruby: unsubscribe(String name, &listener_proc) -objc,swift: unsubscribe(name: String, listener: ARTEventListener) - -Unsubscribe the given listener for the specified event name. This removes an earlier event-specific subscription. - -bq(definition#unsubscribe-listener). -default: unsubscribe(listener) -java: void unsubscribe("MessageListener":#message-listener listener) -csharp: bool Unsubscribe(Action<"Message":#message> handler) -ruby: unsubscribe(&listener_proc) -objc,swift: unsubscribe(listener: ARTEventListener) - -Unsubscribe the given listener (for any/all event names). This removes an earlier subscription. - -
-bq(definition). unsubscribe(String[] names, listener) - -Unsubscribe the given listener from all event names in the array. - -bq(definition). unsubscribe(String name) - -Unsubscribe all listeners for a given event name. - -bq(definition). unsubscribe(String[] names) - -Unsubscribe all listeners for all event names in the array. -
- -bq(definition#unsubscribe-all). -default: unsubscribe() -java: void unsubscribe() -csharp: void Unsubscribe() -objc,swift: unsubscribe() - -Unsubscribes all listeners to messages on this channel. This removes all earlier subscriptions. - -h4. Parameters - -- name := The event name to unsubscribe from
__Type: @String@__ --
names
:= An array of event names to unsubscribe from
__Type: @String[]@__ --
listener
:= is the callback listener function that was previously subscribed --
listener
:= previously registered listener
__Type: "@MessageListener@":#message-listener__ --
&listener_block
:= previously registered listener block --
listener
:= previous return value from a @subscribe@ call --
handler
:= is the lambda expression that was previously subscribed -
-@streamSubscription@ obtained from a subscription can be used to cancel a listener by calling @streamSubscription.cancel@. -
- -h6(#history). -default: history -csharp: History`; - -export const spanWithHashExample = `h6(#state). -default: state -csharp: State - -The current "@io.ably.lib.realtime.ChannelState@":#channel-state @state@"@IO.Ably.Realtime.ChannelState@":#channel-state @state@"@Ably::Realtime::Channel::STATE@":#channel-state @state@"@ARTRealtimeChannelState@":#channel-state"@ChannelState@":#channel-state of this @Channel@. See the supported "channel states":#channel-states for more information.`; - -export const spanWithHashResult = `

stateState

-

The current io.ably.lib.realtime.ChannelState stateIO.Ably.Realtime.ChannelState stateAbly::Realtime::Channel::STATE stateARTRealtimeChannelStateChannelState of this Channel. See the supported channel states for more information.

`; - -export const listDivExample = `
-h4. Parameters - --
callback
:= is a function of the form @function(err)@ and is called once the channel attach succeeds or fails --
&block
:= yields once the channel becomes attached --
callback
:= is a lambda expression of the form @Action@ and is called once the channel attach succeeds or fails --
callback
:= called once the channel becomes attached or if an error occurs -
`; - -export const listDivParsedExample = `
-

Parameters

-
-
callback
-
is a function of the form function(err) and is called once the channel attach succeeds or fails
-
&block
-
yields once the channel becomes attached
-
callback
-
is a lambda expression of the form Action<TimeSpan, ErrorInfo> and is called once the channel attach succeeds or fails
-
callback
-
called once the channel becomes attached or if an error occurs
-
-
-
`; diff --git a/data/transform/retrieve-partials/applyIndent.test.ts b/data/transform/retrieve-partials/applyIndent.test.ts deleted file mode 100644 index 6c4dd8d775..0000000000 --- a/data/transform/retrieve-partials/applyIndent.test.ts +++ /dev/null @@ -1,33 +0,0 @@ -import { applyIndent } from './applyIndent'; - -const docsExample = { - data: `@HistoryRequestParams@ is a type that encapsulates the parameters for a history queries. For example usage see "@Channel#history@@Channel#History@":/api/realtime-sdk/history#channel-history. - -h4. Members - -- Start := _null_ The start of the queried interval
__Type: @DateTimeOffset@__ -- End := _null_ The end of the queried interval
__Type: @DateTimeOffset@__ -- Limit := _null_ By default it is null. Limits the number of items returned by history or stats
__Type: @Integer@__ -- Direction := _Backwards_ Enum which is either @Forwards@ or @Backwards@
__Type: @Direction@ enum__ -- ExtraParameters := Optionally any extra query parameters that may be passed to the query. This is mainly used internally by the library to manage paging.
__Type: @Dictionary@__ -`, - type: 'html', -}; - -describe('Applying indentation to partials works as expected', () => { - it('Applies indents to an example from docs', () => { - const docsData = applyIndent(2)(docsExample).data; - expect(docsData).toMatchInlineSnapshot(` - " @HistoryRequestParams@ is a type that encapsulates the parameters for a history queries. For example usage see "@Channel#history@@Channel#History@":/api/realtime-sdk/history#channel-history. - - h4. Members - - - Start := _null_ The start of the queried interval
__Type: @DateTimeOffset@__ - - End := _null_ The end of the queried interval
__Type: @DateTimeOffset@__ - - Limit := _null_ By default it is null. Limits the number of items returned by history or stats
__Type: @Integer@__ - - Direction := _Backwards_ Enum which is either @Forwards@ or @Backwards@
__Type: @Direction@ enum__ - - ExtraParameters := Optionally any extra query parameters that may be passed to the query. This is mainly used internally by the library to manage paging.
__Type: @Dictionary@__ - " - `); - }); -}); diff --git a/data/transform/retrieve-partials/applyIndent.ts b/data/transform/retrieve-partials/applyIndent.ts deleted file mode 100644 index 3cb15764cf..0000000000 --- a/data/transform/retrieve-partials/applyIndent.ts +++ /dev/null @@ -1,7 +0,0 @@ -import { indent } from '../shared-utilities'; -import { StringContent } from '../StringContentOrderedList'; - -export const applyIndent = (indentation: number) => (content: StringContent) => ({ - ...content, - data: indent(content.data, indentation), -}); diff --git a/data/transform/retrieve-partials/index.js b/data/transform/retrieve-partials/index.js deleted file mode 100644 index a6f2d66f95..0000000000 --- a/data/transform/retrieve-partials/index.js +++ /dev/null @@ -1,66 +0,0 @@ -const DataTypes = require('../../types'); -const { flattenContentOrderedList } = require('../shared-utilities'); -const { applyIndent } = require('./applyIndent'); - -const maybeRetrievePartial = - (graphql) => - async ({ data, type }) => { - if (type !== DataTypes.Partial) { - return { data, type }; - } - // Retrieving data about the partial - // eslint-disable-next-line no-sparse-arrays - const fileName = (data.match(/<%=\s+partial\s+partial_version\('([^')]*)'\)[^%>]*%>/) ?? [, ''])[1]; - - const attributes = data.split(','); - - let attributeObject = {}; - if (attributes.length > 1) { - const attributePairs = attributes - .slice(1) - .map((attr) => { - const pairs = attr.match(/\s+(\w+):\s+(\w+)/); - return pairs.length === 3 ? [pairs[1], pairs[2]] : null; - }) - .filter((x) => !!x); - attributeObject = Object.fromEntries(attributePairs); - } - - // Retrieving the data contained in the partial based on the file name - const result = await graphql(` - query { - fileHtmlPartial(relativePath: { eq:"${fileName}.textile"}) { - contentOrderedList { - data - type - } - } - } - `); - const partial = result.data.fileHtmlPartial; - const retrievePartialFromGraphQL = maybeRetrievePartial(graphql); - let contentOrderedList = partial && partial.contentOrderedList; - if (partial) { - // Repeat this operation on any partials contained inside the partial - contentOrderedList = await Promise.all(contentOrderedList.map(retrievePartialFromGraphQL)); - contentOrderedList = flattenContentOrderedList(contentOrderedList); - - // Finally, apply the indentation specified from the attributeObject and return the data - const indentation = parseInt(attributeObject['indent']); - const applyIndentation = applyIndent(indentation); - if (attributeObject['indent']) { - if (!attributeObject['skip_first_indent']) { - contentOrderedList = contentOrderedList.map(applyIndentation); - } - } - } - - return { - data: contentOrderedList, - type, - }; - }; - -module.exports = { - maybeRetrievePartial, -}; diff --git a/data/transform/shared-utilities/index.js b/data/transform/shared-utilities/index.js deleted file mode 100644 index a74a4e1918..0000000000 --- a/data/transform/shared-utilities/index.js +++ /dev/null @@ -1,18 +0,0 @@ -const indent = (str, indentAmount, spacer = '\t') => { - const indent = new Array(indentAmount + 1).join(spacer); - const result = str.replace(/^(?=.)/gm, indent); - return result; -}; - -const flattenContentOrderedList = (contentOrderedList) => - contentOrderedList.reduce((acc, { data, type }) => { - if (Array.isArray(data)) { - return acc.concat(flattenContentOrderedList(data)); - } - return acc.concat([{ data, type }]); - }, []); - -module.exports = { - indent, - flattenContentOrderedList, -}; diff --git a/data/transform/string-transformation.d.ts b/data/transform/string-transformation.d.ts deleted file mode 100644 index 0a47d6f52d..0000000000 --- a/data/transform/string-transformation.d.ts +++ /dev/null @@ -1 +0,0 @@ -type StringTransformation = (content: string) => string; diff --git a/read-textile.ts b/read-textile.ts deleted file mode 100755 index a0e2d58ad9..0000000000 --- a/read-textile.ts +++ /dev/null @@ -1,235 +0,0 @@ -import readline from 'readline'; -import util from 'util'; -import fs from 'fs'; -import Turndown from 'turndown'; -import * as Diff from 'diff'; - -import { - textileToHtml, - textileToCheerio, - processTextile, - fullyParseTextile, -} from './data/test-utilities/process-textile'; -import { preParserSteps, Step } from './data/cli-functionality/parser-steps/pre-parser'; -import { textileWorkaroundSteps } from './data/cli-functionality/parser-steps/textile-workarounds'; -import { postParserSteps } from './data/cli-functionality/parser-steps/post-parser'; -import { htmlParserSteps } from './data/cli-functionality/parser-steps/html-parser'; -/** - * Flags: - * --diff - output each step with the difference to the last step highlighted - * --diffOnly - output only the difference between each step - */ - -process.on('exit', () => fs.rmSync('./dist', { recursive: true, force: true })); - -const argsToRead = process.argv - .slice(2) - .filter((arg) => !arg.startsWith('--')) - .map((arg) => { - try { - const content = fs.readFileSync(arg); - return content.toString(); - } catch (e) { - //Fine to ignore. - } - return arg; - }) - .map((arg) => arg.replace(/\\n/g, '\n')); - -const flags: Record = process.argv - .slice(2) - .filter((arg) => arg.startsWith('--')) - .reduce((acc, arg) => { - const [key, value] = arg.replace(/^--/, '').split('='); - return { - ...acc, - [key]: value ?? true, - }; - }, {}); - -const rl = readline.createInterface({ - input: process.stdin, - output: process.stdout, -}); - -const question = util.promisify(rl.question).bind(rl); - -const turndownService = new Turndown(); -turndownService.keep(['div', 'span']); - -const queryUser = async (query: string, outputHandler: (answer: string) => void) => { - rl.question(query, outputHandler); -}; - -const logFunctionWithDescription = (step: Step) => { - console.log(step.fn); - if (step.description) { - console.log(`\n\x1b[33m${step.description}\x1b[0m\n`); - } -}; - -const executeSequentially = (queries: string[], outputHandlers: ((answer: string) => void)[]) => { - queries.forEach(async (query, i) => await queryUser(query, outputHandlers[i])); -}; - -const steps = [...preParserSteps, ...textileWorkaroundSteps, ...postParserSteps, ...htmlParserSteps]; - -const logArgProcessingError = (name: string, arg: string, i: number) => - console.error(`\n\nError processing ${name} ${i + 1}:\n${arg}\n`); - -const diffText = (oldText: string, newText: string) => { - const diffResult = Diff.diffLines(oldText, newText); - diffResult.forEach((diffPart) => { - const color = diffPart.added ? '\x1b[32m' : diffPart.removed ? '\x1b[31m' : '\x1b[1;30m'; - console.log(`${color}${diffPart.value}\x1b[0m`); - }); -}; - -const diffOnlyText = (oldText: string, newText: string) => { - const diffResult = Diff.diffLines(oldText, newText); - diffResult.forEach((diffPart) => { - if (diffPart.added) { - console.log(`${'\x1b[32m'}${diffPart.value}\x1b[0m`); - } else if (diffPart.removed) { - console.log(`${'\x1b[31m'}${diffPart.value}\x1b[0m`); - } - }); -}; - -const initialQuery = ['How would you like to debug the textile? (h)tml, (m)arkdown, (s)tep by step or (a)dvanced?']; -const initialOutputHandler = [ - async (answer: string) => { - switch (answer) { - case 'h': - argsToRead.forEach((arg, i) => { - console.log('\nHTML mode\n'); - try { - if (flags.diff) { - diffText(arg, textileToHtml(arg)); - } else if (flags.diffOnly) { - diffOnlyText(arg, textileToHtml(arg)); - } else { - console.log(`\n${textileToHtml(arg)}\n`); - } - } catch (e) { - logArgProcessingError('argument', arg, i); - console.error(e); - } - }); - process.exit(); - break; - case 'm': - argsToRead.forEach((arg, i) => { - console.log('\nMarkdown mode\n'); - try { - const markdown = turndownService.turndown(textileToHtml(arg)); - if (flags.diff) { - diffText(arg, markdown); - } else if (flags.diffOnly) { - diffOnlyText(arg, markdown); - } else { - console.log(`\n${markdown}\n`); - } - } catch (e) { - logArgProcessingError('argument', arg, i); - console.error(e); - } - }); - process.exit(); - break; - case 's': - console.log('\nStep by step mode - \n\x1b[33mwill only operate on first argument provided\x1b[0m\n\n'); - // eslint-disable-next-line no-case-declarations - let result = argsToRead[0]; - // eslint-disable-next-line no-case-declarations - const recursivelyReadSteps = async (i: number) => { - if (i >= steps.length) { - return; - } - const step = steps[i]; - try { - console.log(`\nOutput on step ${i + 1}\n`); - logFunctionWithDescription(step); - if (flags.diff) { - const nextResult = step.fn(result); - diffText(result, nextResult); - result = nextResult; - logFunctionWithDescription(step); - } else if (flags.diffOnly) { - const nextResult = step.fn(result); - diffOnlyText(result, nextResult); - result = nextResult; - } else { - result = step.fn(result); - console.log(`\x1b[32m${result}\x1b[0m\n`); - } - const possiblyQuit = await question('Press enter to proceed, q to quit: '); - // @ts-ignore - if (possiblyQuit === 'q') { - process.exit(); - } - await recursivelyReadSteps(i + 1); - } catch (e) { - logArgProcessingError('argument', result, 0); - logArgProcessingError('step', step.description ?? step.fn.prototype?.name ?? '', i); - console.error(e); - return; - } - return result; - }; - await recursivelyReadSteps(0); - process.exit(); - break; - case 'a': - // eslint-disable-next-line no-case-declarations - const selected = await question( - '\nSelecting from advanced modes, (c)heerio rendered into html, (a)rray of cheerio values, (f)inal objects:', - ); - switch (selected) { - // @ts-ignore - case 'c': - argsToRead.forEach((arg, i) => { - try { - console.log(`\n${textileToCheerio(arg)}\n`); - } catch (e) { - logArgProcessingError('argument', arg, i); - console.error(e); - } - }); - break; - // @ts-ignore - case 'a': - argsToRead.forEach((arg, i) => { - try { - console.log('\n'); - console.log(processTextile(arg)); - console.log('\n'); - } catch { - logArgProcessingError('argument', arg, i); - } - }); - break; - // @ts-ignore - case 'f': - argsToRead.forEach((arg, i) => { - try { - console.log(`\n${JSON.stringify(fullyParseTextile(arg), null, ' ')}\n`); - } catch { - logArgProcessingError('argument', arg, i); - } - }); - break; - default: - process.exit(); - break; - } - process.exit(); - break; - default: - process.exit(); - break; - } - }, -]; - -executeSequentially(initialQuery, initialOutputHandler); diff --git a/src/components/blocks/external-references/AElementHelpers/check-link-is-internal.test.ts b/src/components/blocks/external-references/AElementHelpers/check-link-is-internal.test.ts index b04e2b85d4..86d1833b5a 100644 --- a/src/components/blocks/external-references/AElementHelpers/check-link-is-internal.test.ts +++ b/src/components/blocks/external-references/AElementHelpers/check-link-is-internal.test.ts @@ -1,4 +1,4 @@ -import { assert, constantFrom, property, tuple, webPath, webUrl } from 'fast-check'; +import { assert, property, webPath, webUrl } from 'fast-check'; import { checkLinkIsInternal } from './check-link-is-internal'; describe('Check link is internal: unit tests', () => { diff --git a/src/components/blocks/wrappers/ConditionalChildrenLanguageDisplay.test.js b/src/components/blocks/wrappers/ConditionalChildrenLanguageDisplay.test.js deleted file mode 100644 index 556f026c0a..0000000000 --- a/src/components/blocks/wrappers/ConditionalChildrenLanguageDisplay.test.js +++ /dev/null @@ -1,128 +0,0 @@ -import React from 'react'; -import TestRenderer from 'react-test-renderer'; -import cheerio from 'cheerio'; -import { DEFAULT_LANGUAGE } from '../../../../data/createPages/constants'; -import textile from 'textile-js'; -import { htmlParser } from '../../../../data/html-parser'; -import { liftLangAttributes } from '../../../../data/html-parser/lift-lang-attributes'; -import { postParser } from '../../../../data/transform/post-parser'; -import { preParser } from '../../../../data/transform/pre-parser'; -import ConditionalChildrenLanguageDisplay from './ConditionalChildrenLanguageDisplay'; -import { defaultBlocksFromData } from '../create-blocks/default-blocks-from-data'; - -const rawData = ` --
callback
:= is a function of the form @function(err)@ which is called upon completion --
listener
:= Listener to be notified on completion
__Type: "@CompletionListener@":#completion-listener__ --
callback
:= is an action of the form @Action@ which is called upon completion --
&block
:= yields upon successfully publishing the message --
callback
:= called upon publishing the message, or with an error -`; - -const twoChildrenInstance = TestRenderer.create( - - {defaultBlocksFromData([ - { - name: 'span', - data: 'content', - attribs: { lang: DEFAULT_LANGUAGE }, - }, - { - name: 'span', - data: 'alternative', - attribs: { lang: 'javascript' }, - }, - ])} - , -).root; - -const sameLanguageTwoChildrenInstance = TestRenderer.create( - - {defaultBlocksFromData([ - { - name: 'span', - data: 'content', - attribs: { lang: 'javascript' }, - }, - { - name: 'span', - data: 'alternative', - attribs: { lang: 'javascript' }, - }, - ])} - , -).root; - -describe('ConditionalChildrenLanguageDisplay only displays one child of alternatives', () => { - it('A basic instance of two children with different lang attributes only shows the default language option', () => { - expect(twoChildrenInstance.findAllByType('span')).toHaveLength(1); - }); - - it('Two different instances in a row shows both language options', () => { - expect(sameLanguageTwoChildrenInstance.findAllByType('span')).toHaveLength(2); - }); -}); - -describe('Integration: ConditionalChildrenLanguageDisplay only displays one
pair of children from alternatives for parsed definition lists', () => { - const parsedData = postParser(textile(preParser(rawData))); - it('Text parser stage returns expected results', () => { - expect(parsedData.replace(/\s/g, '')).toEqual( - `
-
callback
-
is a function of the form function(err) which is called upon completion
-
listener
-
Listener to be notified on completion
Type: CompletionListener
-
callback
-
is an action of the form Action<bool, ErrorInfo> which is called upon completion
-
&block
-
yields upon successfully publishing the message
-
callback
-
called upon publishing the message, or with an error
-
`.replace(/\s/g, ''), - ); - }); - - // cf. lift-language-attributes.test.js - // Included here to allow for easy debugging of which particular stage of the process is broken - it('Lift language attributes stage returns expected results', () => { - const loadedDom = cheerio.load(parsedData, null); - liftLangAttributes(loadedDom); - expect(loadedDom('body *').html().replace(/\s/g, '')).toEqual( - `
callback
is a function of the form function(err) which is called upon completion
-
listener
Listener to be notified on completion
Type: CompletionListener
-
callback
is an action of the form Action<bool, ErrorInfo> which is called upon completion
-
&block
yields upon successfully publishing the message
-
callback
called upon publishing the message, or with an error
-`.replace(/\s/g, ''), - ); - }); - - const htmlParsed = htmlParser(parsedData); - it('HTML parser stage returns expected results', () => { - expect(htmlParsed[0].data[0].data).toEqual( - expect.arrayContaining([ - expect.objectContaining({ - attribs: { lang: 'nodejs' }, - name: 'div', - data: expect.arrayContaining([ - expect.objectContaining({ - name: 'dt', - }), - expect.objectContaining({ - name: 'dd', - }), - ]), - }), - ]), - ); - }); - - it('ConditionalChildrenLanguageDisplay displays the expected results from HTML data', () => { - const renderedData = TestRenderer.create( - {defaultBlocksFromData(htmlParsed)}, - ); - const tree = renderedData.toJSON(); - expect(tree).toMatchSnapshot(); - expect(renderedData.root.findAllByType('dt')).toHaveLength(1); - expect(renderedData.root.findAllByType('dd')).toHaveLength(1); - }); -}); diff --git a/src/components/blocks/wrappers/__snapshots__/ConditionalChildrenLanguageDisplay.test.js.snap b/src/components/blocks/wrappers/__snapshots__/ConditionalChildrenLanguageDisplay.test.js.snap deleted file mode 100644 index 159ca3d19c..0000000000 --- a/src/components/blocks/wrappers/__snapshots__/ConditionalChildrenLanguageDisplay.test.js.snap +++ /dev/null @@ -1,52 +0,0 @@ -// Jest Snapshot v1, https://goo.gl/fbAQLP - -exports[`Integration: ConditionalChildrenLanguageDisplay only displays one
pair of children from alternatives for parsed definition lists ConditionalChildrenLanguageDisplay displays the expected results from HTML data 1`] = ` -
- - -
-
-
- callback -
-
-
- is a function of the form - - function(err) - - which is called upon completion -
-
- - - - - - - - - - - - - - - - - - - - -
-`; From d09f942dd45cd658e738a7ad7eeeaec1ae10a5a9 Mon Sep 17 00:00:00 2001 From: Kenneth Kalmer Date: Wed, 26 Nov 2025 21:55:18 +0000 Subject: [PATCH 3/6] Delete textile content files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove all textile content files from the repository. These files have already been converted to MDX format and are no longer needed. Deleted: - content/partials/ directory (96 textile files) - index.textile The content now exists exclusively in MDX format. Build continues to work with 241 pages generated from MDX sources. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../_authentication_capabilities.textile | 21 - .../_authentication_comparison.textile | 13 - .../events/_batched_event_headers.textile | 4 - .../general/events/_batched_events.textile | 154 ----- .../events/_enveloped_event_headers.textile | 4 - .../general/events/_enveloped_events.textile | 89 --- .../events/_events_examples_intro.textile | 1 - .../_non_enveloped_event_headers.textile | 13 - .../events/_non_enveloped_events.textile | 39 -- content/partials/realtime/_stats.textile | 53 -- content/partials/rest/_request.textile | 71 --- content/partials/rest/_stats.textile | 44 -- .../shared/_channel_enumeration.textile | 28 - .../partials/shared/_channel_metadata.textile | 10 - .../shared/_channel_namespaces.textile | 20 - .../partials/shared/_presence_states.textile | 11 - .../shared/_token_auth_methods.textile | 11 - .../partials/types/_ably_exception.textile | 8 - content/partials/types/_auth_options.textile | 28 - .../types/_base_ably_exception.textile | 13 - .../_batch_presence_failure_result.textile | 8 - .../_batch_presence_success_result.textile | 8 - .../_batch_publish_failure_result.textile | 8 - .../types/_batch_publish_spec.textile | 8 - .../_batch_publish_success_result.textile | 8 - content/partials/types/_batch_result.textile | 10 - .../partials/types/_channel_details.textile | 53 -- content/partials/types/_channel_event.textile | 132 ----- .../partials/types/_channel_options.textile | 47 -- content/partials/types/_channel_state.textile | 137 ----- .../types/_channel_state_change.textile | 9 - .../types/_channel_state_listener.textile | 8 - content/partials/types/_cipher_params.textile | 16 - .../partials/types/_client_options.textile | 68 --- .../types/_completion_listener.textile | 11 - .../partials/types/_connection_event.textile | 160 ------ .../partials/types/_connection_state.textile | 151 ----- .../types/_connection_state_change.textile | 12 - .../types/_connection_state_listener.textile | 8 - content/partials/types/_deferrable.textile | 30 - .../partials/types/_device_details.textile | 24 - content/partials/types/_error_info.textile | 198 ------- .../types/_history_request_params.textile | 9 - .../types/_http_paginated_response.textile | 110 ---- .../types/_last_connection_details.textile | 14 - content/partials/types/_local_device.textile | 30 - .../partials/types/_location_pushes.textile | 8 - content/partials/types/_message.textile | 131 ----- .../partials/types/_message_action.textile | 61 -- .../types/_message_annotations.textile | 7 - .../partials/types/_message_listener.textile | 8 - .../partials/types/_paginated_result.textile | 212 ------- content/partials/types/_param.textile | 10 - .../partials/types/_presence_action.textile | 146 ----- .../partials/types/_presence_listener.textile | 8 - .../partials/types/_presence_message.textile | 66 --- content/partials/types/_push_admin.textile | 527 ------------------ content/partials/types/_push_channel.textile | 100 ---- .../types/_push_channel_subscription.textile | 56 -- content/partials/types/_push_device.textile | 51 -- .../types/_realtime_client_options.textile | 22 - .../_realtime_client_options_intro.textile | 12 - .../types/_rest_client_options.textile | 3 - .../types/_rest_client_options_intro.textile | 14 - content/partials/types/_stats.textile | 37 -- .../partials/types/_stats_granularity.textile | 45 -- .../types/_stats_request_params.textile | 10 - content/partials/types/_token_details.textile | 55 -- content/partials/types/_token_params.textile | 33 -- content/partials/types/_token_request.textile | 41 -- .../_token_revocation_failure_result.textile | 8 - .../types/_token_revocation_options.textile | 8 - .../_token_revocation_success_result.textile | 10 - ..._token_revocation_target_specifier.textile | 8 - index.textile | 30 - 75 files changed, 3639 deletions(-) delete mode 100644 content/partials/core-features/_authentication_capabilities.textile delete mode 100644 content/partials/core-features/_authentication_comparison.textile delete mode 100644 content/partials/general/events/_batched_event_headers.textile delete mode 100644 content/partials/general/events/_batched_events.textile delete mode 100644 content/partials/general/events/_enveloped_event_headers.textile delete mode 100644 content/partials/general/events/_enveloped_events.textile delete mode 100644 content/partials/general/events/_events_examples_intro.textile delete mode 100644 content/partials/general/events/_non_enveloped_event_headers.textile delete mode 100644 content/partials/general/events/_non_enveloped_events.textile delete mode 100644 content/partials/realtime/_stats.textile delete mode 100644 content/partials/rest/_request.textile delete mode 100644 content/partials/rest/_stats.textile delete mode 100644 content/partials/shared/_channel_enumeration.textile delete mode 100644 content/partials/shared/_channel_metadata.textile delete mode 100644 content/partials/shared/_channel_namespaces.textile delete mode 100644 content/partials/shared/_presence_states.textile delete mode 100644 content/partials/shared/_token_auth_methods.textile delete mode 100644 content/partials/types/_ably_exception.textile delete mode 100644 content/partials/types/_auth_options.textile delete mode 100644 content/partials/types/_base_ably_exception.textile delete mode 100644 content/partials/types/_batch_presence_failure_result.textile delete mode 100644 content/partials/types/_batch_presence_success_result.textile delete mode 100644 content/partials/types/_batch_publish_failure_result.textile delete mode 100644 content/partials/types/_batch_publish_spec.textile delete mode 100644 content/partials/types/_batch_publish_success_result.textile delete mode 100644 content/partials/types/_batch_result.textile delete mode 100644 content/partials/types/_channel_details.textile delete mode 100644 content/partials/types/_channel_event.textile delete mode 100644 content/partials/types/_channel_options.textile delete mode 100644 content/partials/types/_channel_state.textile delete mode 100644 content/partials/types/_channel_state_change.textile delete mode 100644 content/partials/types/_channel_state_listener.textile delete mode 100644 content/partials/types/_cipher_params.textile delete mode 100644 content/partials/types/_client_options.textile delete mode 100644 content/partials/types/_completion_listener.textile delete mode 100644 content/partials/types/_connection_event.textile delete mode 100644 content/partials/types/_connection_state.textile delete mode 100644 content/partials/types/_connection_state_change.textile delete mode 100644 content/partials/types/_connection_state_listener.textile delete mode 100644 content/partials/types/_deferrable.textile delete mode 100644 content/partials/types/_device_details.textile delete mode 100644 content/partials/types/_error_info.textile delete mode 100644 content/partials/types/_history_request_params.textile delete mode 100644 content/partials/types/_http_paginated_response.textile delete mode 100644 content/partials/types/_last_connection_details.textile delete mode 100644 content/partials/types/_local_device.textile delete mode 100644 content/partials/types/_location_pushes.textile delete mode 100644 content/partials/types/_message.textile delete mode 100644 content/partials/types/_message_action.textile delete mode 100644 content/partials/types/_message_annotations.textile delete mode 100644 content/partials/types/_message_listener.textile delete mode 100644 content/partials/types/_paginated_result.textile delete mode 100644 content/partials/types/_param.textile delete mode 100644 content/partials/types/_presence_action.textile delete mode 100644 content/partials/types/_presence_listener.textile delete mode 100644 content/partials/types/_presence_message.textile delete mode 100644 content/partials/types/_push_admin.textile delete mode 100644 content/partials/types/_push_channel.textile delete mode 100644 content/partials/types/_push_channel_subscription.textile delete mode 100644 content/partials/types/_push_device.textile delete mode 100644 content/partials/types/_realtime_client_options.textile delete mode 100644 content/partials/types/_realtime_client_options_intro.textile delete mode 100644 content/partials/types/_rest_client_options.textile delete mode 100644 content/partials/types/_rest_client_options_intro.textile delete mode 100644 content/partials/types/_stats.textile delete mode 100644 content/partials/types/_stats_granularity.textile delete mode 100644 content/partials/types/_stats_request_params.textile delete mode 100644 content/partials/types/_token_details.textile delete mode 100644 content/partials/types/_token_params.textile delete mode 100644 content/partials/types/_token_request.textile delete mode 100644 content/partials/types/_token_revocation_failure_result.textile delete mode 100644 content/partials/types/_token_revocation_options.textile delete mode 100644 content/partials/types/_token_revocation_success_result.textile delete mode 100644 content/partials/types/_token_revocation_target_specifier.textile delete mode 100644 index.textile diff --git a/content/partials/core-features/_authentication_capabilities.textile b/content/partials/core-features/_authentication_capabilities.textile deleted file mode 100644 index 10f21c78d3..0000000000 --- a/content/partials/core-features/_authentication_capabilities.textile +++ /dev/null @@ -1,21 +0,0 @@ -The following capability operations are available for API keys and issued tokens: - -- subscribe := can subscribe to messages, objects, and presence state change messages on channels, and get the presence set of a channel -- publish := can publish messages to channels -- presence := can register presence on a channel (enter, update and leave) -- object-subscribe := can subscribe to updates to objects on a channel -- object-publish := can update objects on a channel -- annotation-subscribe := can subscribe to individual annotations on a channel -- annotation-publish := can publish annotations to messages on a channel -- history := can retrieve message and presence state history on channels -- stats := can retrieve current and historical usage statistics for an app -- push-subscribe := can subscribe devices for push notifications -- push-admin := can manage device registrations and push subscriptions for all devices in an app -- channel-metadata := can get metadata for a channel, and enumerate channels -- privileged-headers := can set data in the privileged section of the "message extras":/docs/api/realtime-sdk/messages#extras - -Read the "capabilities docs":/docs/auth/capabilities to get a more thorough overview of how capabilities can be used to secure your application. - -While most of these capabilities need to be enabled for the resource you're using them with, as described in "resource names and wildcards":/docs/auth/capabilities#wildcards, there are exceptions. The @stats@ permission only does something when attached to the wildcard resource @'*'@, or a resource that contains that as a subset, such as @'[*]*'@, since stats are app-wide. - -The @channel-metadata@ permission works both ways. When associated with a specific channel or set of channels it allows you to "query the metadata of a channel":/docs/metadata-stats/metadata/rest to request its status. When associated with the wildcard resource @'*'@ it takes on an additional meaning: as well as allowing channel status requests for all channels, it also allows you to "enumerate all active channels":/docs/metadata-stats/metadata/rest#enumerate. diff --git a/content/partials/core-features/_authentication_comparison.textile b/content/partials/core-features/_authentication_comparison.textile deleted file mode 100644 index 8f3fb5ff5c..0000000000 --- a/content/partials/core-features/_authentication_comparison.textile +++ /dev/null @@ -1,13 +0,0 @@ -When deciding on which authentication method you will be using, it is recommended you bear in mind the "principle of least privilege":https://en.wikipedia.org/wiki/Principle_of_least_privilege. - -A client should ideally only possess the credentials and rights that it needs to accomplish what it wants. This way, if the credentials are compromised, the rights that can be abused by an attacker are minimized. - -The following table provides guidelines on what to consider when choosing your authentication method. Many applications will most naturally use a mixed strategy: one or more trusted application servers will use basic authentication to access the service and issue tokens over HTTPS, whereas remote browsers and devices will use individually issued tokens: - -|_. Scenario |_. "Basic":/docs/auth/basic |_. "Token":/docs/auth/token |_. Description | -| Your scripts may be exposed | No | Yes | If the script, program or system holding the key is exposed, for example on a user's device, you should not embed an "API key":/docs/auth#api-key and instead use "Token Authentication":/docs/auth/token. If the script is on a secure environment such as your own server, an "API key":/docs/auth#api-key with "Basic Authentication":/docs/auth#basic is fine. | -| Your connection may be insecure | No | Yes | If there is a risk of exposure of the client's credentials, either directly or over an insecure, or insecurely proxied, connection, "Token Authentication":/docs/auth/token should be used. If you are sure the connection is secure and unmediated, "Basic Authentication":/docs/auth/basic is acceptable. | -| You have no server to control access | Yes | No | If you do not have your own server to perform authentication and provide "tokens":/docs/api/realtime-sdk/authentication#tokens to users, you'll need to use "Basic Authentication":/docs/auth/basic. | -| You require fine-grained access control | No | Yes | If you need to provide "privileges":/docs/auth/capabilities on a user-by-user basis, you'd be better using "Token Authentication":/docs/auth/token. If you only need a few access control groups, "Basic Authentication":/docs/auth/basic is reasonable. | -| Users need restricted periods of access | No | Yes | If you need users to only have access for a certain period of time, or the ability to revoke access, Token Authentication is needed. If users are able to always have access, Basic Authentication is acceptable. | -| Users need to identify themselves | Partial | Yes | If the user can be trusted to "identify":/docs/auth/identified-clients itself, "Basic Authentication":/docs/auth/basic is fine. If the user cannot be trusted however, "Token Authentication":/docs/auth/token is better as it allows for a trusted token distributor to identify the user instead. | diff --git a/content/partials/general/events/_batched_event_headers.textile b/content/partials/general/events/_batched_event_headers.textile deleted file mode 100644 index 01be7b0d04..0000000000 --- a/content/partials/general/events/_batched_event_headers.textile +++ /dev/null @@ -1,4 +0,0 @@ -Batched events will have the following headers: - -- content-type := the type of the payload. This will be @application/json@ or @application/x-msgpack@ -- x-ably-version := the version of the Webhook. At present this should be @1.2@ diff --git a/content/partials/general/events/_batched_events.textile b/content/partials/general/events/_batched_events.textile deleted file mode 100644 index 1339b58e81..0000000000 --- a/content/partials/general/events/_batched_events.textile +++ /dev/null @@ -1,154 +0,0 @@ -Each batched message will have the following fields: - -- name := the event type, for example @presence.message@, @channel.message@ or @channel.closed@ -- webhookId := an internal unique ID for the configured webhook -- source := the source for the webhook, which will be one of @channel.message@, @channel.presence@, @channel.lifecycle@, or @channel.occupancy@ -- timestamp := a timestamp represented as milliseconds since the epoch for the presence event -- data := an object containing the data of the event defined below in "JSONPath format":https://goessner.net/articles/JsonPath/ - -h4(#batch-example-message). Batched message events - -For @message@ events, @data@ will contain: - -- data.channelId := name of the channel that the presence event belongs to -- data.site := an internal site identifier indicating which primary datacenter the member is present in -- data.messages := an @Array@ of raw messages - -The following is an example of a batched @message@ payload: - -```[json] -{ - "items": [{ - "webhookId": "ABcDEf", - "source": "channel.message", - "serial": "a7bcdEFghIjklm123456789:4", - "timestamp": 1562124922426, - "name": "channel.message", - "data": { - "channelId": "chat-channel-4", - "site": "eu-west-1-A", - "messages": [{ - "id": "ABcDefgHIj:1:0", - "clientId": "user-3", - "connectionId": "ABcDefgHIj", - "timestamp": 1123145678900, - "data": "the message data", - "name": "a message name" - }] - } - }] -} -``` - -h5(#batch-example-message-decoding). Decoding batched messages - -Messages sent "over the realtime service":/docs/channels are automatically decoded into "@Message@":/docs/api/realtime-sdk/types#message objects by the Ably client library. With webhooks you need to to do this explicitly, using "@Message.fromEncodedArray@":/docs/api/realtime-sdk/messages#message-from-encoded-array on the @data.messages@ array, or "@Message.fromEncoded@":/docs/api/realtime-sdk/messages#message-from-encoded on an individual member of that array. This will transform them into an array of "@Message@":/docs/api/realtime-sdk/types#message objects (or in the case of @fromEncoded@, an individual "@Message@":/docs/api/realtime-sdk/types#message). This has several advantages, e.g.: - -* It will fully decode any @data@ (using the @encoding@) back into the same datatype that it was sent in (or an equivalent in each client library's language) -* If you are using "encryption":/docs/channels/options/encryption, you can pass your encryption key to the method and it will decrypt the @data@ for you - -We recommend you do this for all messages you receive over webhooks. For example (using ably-js): - -```[javascript] -webhookMessage.items.forEach((item) => { - const messages = Ably.Realtime.Message.fromEncodedArray(item.data.messages); - messages.forEach((message) => { - console.log(message.toString()); - }) -}) -``` - -h4(#batch-example-presence). Batched presence events - -For @presence@ events, @data@ will contain: - -- data.channelId := name of the channel that the presence event belongs to -- data.site := an internal site identifier indicating which primary datacenter the member is present in -- data.presence := an @Array@ of raw presence messages - -The following is an example of a batched @presence@ payload: - -```[json] -{ - "items": [{ - "webhookId": "ABcDEf", - "source": "channel.presence", - "serial": "a7bcdEFghIjklm123456789:4", - "timestamp": 1562124922426, - "name": "presence.message", - "data": { - "channelId": "education-channel", - "site": "eu-west-1-A", - "presence": [{ - "id": "ABcDefgHIj:1:0", - "clientId": "bob", - "connectionId": "ABcDefgHIj", - "timestamp": 1123145678900, - "data": "the message data", - "action": 4 - }] - } - }] -} -``` - -h5(#batch-example-presence-decoding). Decoding batched presence messages - -Presence messages sent "over the realtime service":/docs/channels are automatically decoded into "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message objects by the Ably client library. With webhooks you need to to do this explicitly, using "@PresenceMessage.fromEncodedArray@":/docs/api/realtime-sdk/presence#presence-from-encoded-array on the @data.presence@ array, or "@PresenceMessage.fromEncoded@":/docs/api/realtime-sdk/presence#presence-from-encoded on an individual member of that array. This will transform them into an array of "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message objects (or in the case of @fromEncoded@, an individual "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message). This has several advantages, e.g.: - -* It will decode the (numerical) action into a "@Presence action@":/docs/api/realtime-sdk/presence#presence-action string (such as "@enter@", "@update@", or "@leave@") -* It will fully decode any @data@ (using the @encoding@) back into the same datatype that it was sent in (or an equivalent in each client library's language) -* If you are using "encryption":/docs/channels/options/encryption, you can pass your encryption key to the method and it will decrypt the @data@ for you - -We recommend you do this for all presence messages you receive over webhooks. For example (using ably-js): - -```[javascript] -webhookMessage.items.forEach((item) => { - const messages = Ably.Realtime.PresenceMessage.fromEncodedArray(item.data.messages); - messages.forEach((message) => { - console.log(message.toString()); - }) -}) -``` - -h4(#batch-example-lifecycle). Batched channel lifecycle events - -For @channel lifecycle@ events, @data@ will contain: - -- data.channelId := name of the channel that the presence event belongs to -- data.status := a "@ChannelStatus@":/docs/api/realtime-sdk/channel-metadata#channel-details object - -The @name@ of a @channel.lifecycle@ event will be @channel.opened@ or @channel.closed@. - -The following is an example of a batched @channel lifecycle@ payload: - -```[json] -{ - "items": [{ - "webhookId": "ABcDEf", - "source": "channel.lifecycle", - "timestamp": 1562124922426, - "serial": "a7bcdEFghIjklm123456789:4", - "name": "channel.opened", - "data": { - "channelId": "chat-channel-5", - "name": "chat-channel-5", - "status": { - "isActive": true, - "occupancy": { - "metrics": { - "connections": 1, - "publishers": 1, - "subscribers": 1, - "presenceConnections": 1, - "presenceMembers": 0, - "presenceSubscribers": 1, - "objectPublishers": 1, - "objectSubscribers": 1 - } - } - } - } - }] -} -``` diff --git a/content/partials/general/events/_enveloped_event_headers.textile b/content/partials/general/events/_enveloped_event_headers.textile deleted file mode 100644 index 4ace3185c9..0000000000 --- a/content/partials/general/events/_enveloped_event_headers.textile +++ /dev/null @@ -1,4 +0,0 @@ -Enveloped events will have the following headers: - -- x-ably-version := the version of the Webhook. At present this should be @1.2@ -- content-type := the type of the payload. This will be @application/json@ or @application/x-msgpack@ for "enveloped":#envelope messages diff --git a/content/partials/general/events/_enveloped_events.textile b/content/partials/general/events/_enveloped_events.textile deleted file mode 100644 index af557aba55..0000000000 --- a/content/partials/general/events/_enveloped_events.textile +++ /dev/null @@ -1,89 +0,0 @@ -Each enveloped message will have the following fields: - -- source := the source for the webhook, which will be one of @channel.message@, @channel.presence@, @channel.lifecycle@, or @channel.occupancy@ -- appId := the Ably app this message came from -- channel := the Ably channel where the event occurred -- site := the Ably datacenter which sent the message -- timestamp := a timestamp represented as milliseconds since the epoch for the presence event - -In addition, it will contain another field which will contain the actual message, which is named according to the message type. - -h4(#envelope-example-message). Enveloped message events - -For @message@ events, the @messages@ array contains a raw message. - -The following is an example of an enveloped @message@ payload: - -```[json] -{ - "source": "channel.message", - "appId": "aBCdEf", - "channel": "channel-name", - "site": "eu-central-1-A", - "ruleId": "1-a2Bc", - "messages": [{ - "id": "ABcDefgHIj:1:0", - "connectionId": "ABcDefgHIj", - "timestamp": 1123145678900, - "data": "some message data", - "name": "my message name" - }] -} -``` - -h5(#envelope-example-message-decoding). Decoding enveloped messages - -Messages sent "over the realtime service":/docs/channels are automatically decoded into "@Message@":/docs/api/realtime-sdk/types#message objects by the Ably client library. With webhooks you need to to do this explicitly, using "@Message.fromEncodedArray@":/docs/api/realtime-sdk/messages#message-from-encoded-array on the @messages@ array, or "@Message.fromEncoded@":/docs/api/realtime-sdk/messages#message-from-encoded on an individual member of that array. This will transform them into an array of "@Message@":/docs/api/realtime-sdk/types#message objects (or in the case of @fromEncoded@, an individual "@Message@":/docs/api/realtime-sdk/types#message). This has several advantages, e.g.: - -* It will fully decode any @data@ (using the @encoding@) back into the same datatype that it was sent in (or an equivalent in each client library's language) -* If you are using "encryption":/docs/channels/options/encryption, you can pass your encryption key to the method and it will decrypt the @data@ for you - -We recommend you do this for all messages you receive over webhooks. For example (using ably-js): - -```[javascript] -const messages = Ably.Realtime.Message.fromEncodedArray(item.messages); -messages.forEach((message) => { - console.log(message.toString()); -}) -``` - -h4(#envelope-example-presence). Enveloped presence events - -For @presence@ events, the @presence@ array contains a raw presence message. - -The following is an example of of an enveloped @message@ payload with a @presence@ array: - -```[json] -{ - "source": "channel.message", - "appId": "aBCdEf", - "channel": "channel-name", - "site": "eu-central-1-A", - "ruleId": "1-a2Bc", - "presence": [{ - "id": "abCdEFgHIJ:1:0", - "clientId": "bob", - "connectionId": "Ab1CDE2FGh", - "timestamp": 1582270137276, - "data": "some data in the presence object", - "action": 4 - }] -} -``` - -h5(#envelope-example-presence-decoding). Decoding enveloped presence messages - -Presence messages sent "over the realtime service":/docs/channels are automatically decoded into "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message objects by the Ably client library. With webhooks you need to to do this explicitly, using "@PresenceMessage.fromEncodedArray@":/docs/api/realtime-sdk/presence#presence-from-encoded-array on the @presence@ array, or "@PresenceMessage.fromEncoded@":/docs/api/realtime-sdk/presence#presence-from-encoded on an individual member of that array. This will transform them into an array of "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message objects (or in the case of @fromEncoded@, an individual "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message). This has several advantages, e.g.: - -* It will decode the (numerical) action into a "@Presence action@":/docs/api/realtime-sdk/presence#presence-action string (such as "@enter@", "@update@", or "@leave@") -* It will fully decode any @data@ (using the @encoding@) back into the same datatype that it was sent in (or an equivalent in each client library's language) -* If you are using "encryption":/docs/channels/options/encryption, you can pass your encryption key to the method and it will decrypt the @data@ for you - -We recommend you do this for all presence messages you receive over webhooks. For example (using ably-js): - -```[javascript] -const messages = Ably.Realtime.PresenceMessage.fromEncodedArray(item.messages); -messages.forEach((message) => { - console.log(message.toString()); -}) -``` \ No newline at end of file diff --git a/content/partials/general/events/_events_examples_intro.textile b/content/partials/general/events/_events_examples_intro.textile deleted file mode 100644 index eac29ca928..0000000000 --- a/content/partials/general/events/_events_examples_intro.textile +++ /dev/null @@ -1 +0,0 @@ -Given the various potential combinations of @enveloped@, @batched@ and message sources, it can be good to know what to expect given certain combinations of rules. diff --git a/content/partials/general/events/_non_enveloped_event_headers.textile b/content/partials/general/events/_non_enveloped_event_headers.textile deleted file mode 100644 index 60799d64cb..0000000000 --- a/content/partials/general/events/_non_enveloped_event_headers.textile +++ /dev/null @@ -1,13 +0,0 @@ -Non-enveloped events have quite a few headers, in order to provide context to the data sent in the payload. These are: - -- content-type := the type of the payload. This can be either @application/json@, @text/plain@, or @application/octet-stream@, depending on if it's @JSON@, @text@, or @binary@ respectively -- x-ably-version := the version of the Webhook. At present this should be @1.2@ -- x-ably-envelope-appid := the "app ID":/docs/ids-and-keys/ which the message came from -- x-ably-envelope-channel := the Ably channel which the message came from -- x-ably-envelope-rule-id := the Ably rule ID which was activated to send this message -- x-ably-envelope-site := the Ably datacenter which sent the message -- x-ably-envelope-source := the "source":#sources for the webhook, which will be one of @channel.message@, @channel.presence@, @channel.lifecycle@, or @channel.occupancy@ -- x-ably-message-client-id := the client ID of the connection which sent the event -- x-ably-message-connection-id := the connection ID responsible for the initial event -- x-ably-message-id := the message's unique ID -- x-ably-message-timestamp := the time the message was originally sent diff --git a/content/partials/general/events/_non_enveloped_events.textile b/content/partials/general/events/_non_enveloped_events.textile deleted file mode 100644 index ba7e21569f..0000000000 --- a/content/partials/general/events/_non_enveloped_events.textile +++ /dev/null @@ -1,39 +0,0 @@ -h4(#no-envelope-example-message). Non-enveloped message events - -For @message@ events, there will be the additional headers: - -- x-ably-message-name := The "name":/docs/api/realtime-sdk/messages#name of the @Message@ - -The payload will contain the "data":/docs/api/realtime-sdk/messages#data of the @Message@. - -For example, if you sent the following curl message, which sends a JSON message to the channel @my_channel@: - -```[curl] -curl -X POST https://main.realtime.ably.net/channels/my_channel/messages \ - -u "{{API_KEY}}" \ - -H "Content-Type: application/json" \ - --data '{ "name": "publish", "data": "example" }' -``` - -The @x-ably-message-name@ header would be @publish@, and the payload would be @example@. - -h4(#no-envelope-example-presence). Non-enveloped presence events - -For @Presence@ events, there will be the additional headers: - -- x-ably-message-action := the action performed by the event (@update@, @enter@, @leave@) - -The payload will contain the "data":/docs/api/realtime-sdk/presence#presence-message of the @Presence@ message. - -For example, if a "client enters":/docs/api/realtime-sdk/presence#enter a channel's presence with the following code: - -```[jsall] -realtime = new Ably.Realtime({ - key: '{{API_KEY}}', - clientId: 'bob' -}); -channel = realtime.channels.get('some_channel'); -await channel.presence.enter('some data'); -``` - -Then the @x-ably-message-action@ would be @enter@, the @x-ably-message-client-id@ would be "bob", and the payload would be "some data". diff --git a/content/partials/realtime/_stats.textile b/content/partials/realtime/_stats.textile deleted file mode 100644 index 8315a8eead..0000000000 --- a/content/partials/realtime/_stats.textile +++ /dev/null @@ -1,53 +0,0 @@ -h4. Parameters - -- optionsqueryparams := an optional objectHash@ARTStatsQuery@@StatsRequestParams@"@Param@[]":#param array containing the query parameters set of parameters used to specify which statistics are retrieved. If not specified the default parameters will be used - --
&block
:= yields a @PaginatedResult@ object --
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTStats":/docs/api/rest-sdk/types#stats> object or an error - -h4. @options@ parameters@ARTStatsQuery@ properties@StatsRequestParams@ properties@params@ properties - -The following options, as defined in the "REST @/stats@ API":/docs/api/rest-api#stats endpoint, are permitted: - -- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved
__Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__ -- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved
__Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__ -- direction:directionDirection := _backwards_ @:forwards@ or @:backwards@@forwards@ or @backwards@
__Type: @String@@Symbol@@Direction@ enum__ -- limit:limitLimit := _100_ maximum number of stats to retrieve up to 1,000
__Type: @Integer@@Number@__ -- unit:unitUnit := _minute_ @:minute@, @:hour@, @:day@ or @:month@.@minute@, @hour@, @day@ or @month@. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query
__Type: @String@"@StatsIntervalGranularity@":/docs/api/realtime-sdk/types#stats-granularity"@ARTStatsGranularity@":#stats-granularity@Symbol@"@StatsIntervalGranularity@":/docs/api/realtime-sdk/types#stats-granularity enum__ - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result object containing an array of "@Stats@":/docs/api/realtime-sdk/types#stats objects. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object. - -blang[objc,swift]. - h4. Callback result - - On success, @result@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@Stats@":/docs/api/realtime-sdk/types#stats objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods. - - On failure to retrieve stats, @err@ contains an "@ErrorInfo@":#error-info object with an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation. - -blang[java]. - h4. Returns - - On success, the returned "@PaginatedResult@":#paginated-result encapsulates an array of "@Stats@":/docs/api/realtime-sdk/types#stats objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods. - - Failure to retrieve the stats will raise an "@AblyException@":/docs/api/realtime-sdk/types#ably-exception - -blang[csharp]. - h4. Returns - - Returns a @Task@ which needs to be awaited. - - On success, the returned "@PaginatedResult@":#paginated-result encapsulates an array of "@Stats@":/docs/api/realtime-sdk/types#stats objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@NextAsync@":#paginated-result and "@FirstAsync@":#paginated-result methods. - - Failure to retrieve the stats will raise an "@AblyException@":/docs/api/realtime-sdk/types#ably-exception - -blang[ruby]. - h4. Returns - - A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the stats method. - - On success, the registered success callbacks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method yields a "PaginatedResult":#paginated-result that encapsulates an array of "@Stats@":/docs/api/realtime-sdk/types#stats objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods. - - Failure to retrieve the stats will trigger the errback callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":#error-info object containing an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation. diff --git a/content/partials/rest/_request.textile b/content/partials/rest/_request.textile deleted file mode 100644 index ae7a9faa98..0000000000 --- a/content/partials/rest/_request.textile +++ /dev/null @@ -1,71 +0,0 @@ -h6(#request). - default: request - go,csharp: Request - -bq(definition). - default: request(String method, String path, Object params, Object body, Object headers, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response results)) - jsall: request(method, path, version, params?, body?, headers?): Promise<"HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response> - ruby,php: "HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response request(String method, String path, Object params, Object body, Object headers) - python: publish(method=String, path=String, params=Object, body=Object, headers=Object) - java: "HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response request(String method, String path, Object params, Object body, Object headers) - csharp: Task<"HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response> Request(string method, string path, Dictionary requestParams, JToken body, Dictionary headers) - objc,swift: request(method: String, path: String, params: Object?, body: Object?, headers: Object?, callback: ("ARTHttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response, ARTErrorInfo?) -> Void) - go: "HTTPPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response Request(method string, path string, params PaginateParams, body interface, headers http.Header) - -Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to handle authentication, paging, fallback hosts, MsgPack and JSON support, etc. themselves. - -h4. Parameters - -- method := either @get@, @post@, @put@, @patch@ or @delete@.
__Type: Stringstring__ -- path := the path to query.
__Type: Stringstring__ - --
version
:= version of the REST API to use.
__Type: Number__ - -- params := (optional) any querystring parameters needed.
__Type: ObjectPaginateParamsDictionary__ -- body := (optional; for @post@, @put@ and @patch@ methods) the body of the request, as anything that can be serialized into JSON, such as an @Object@ or @Array@.a JToken.
__Type: SerializableinterfaceJToken__ -- headers := (optional) any headers needed. If provided, these will be mixed in with the default library headers.
__Type: Objecthttp.HeaderDictionary__ - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with the "@HttpPaginatedResponse@":/docs/api/realtime-sdk/types#http-paginated-response object returned by the HTTP request. The response object will contain an empty or JSON-encodable object. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object. - -blang[objc,swift]. - h4. Callback result - - On successfully receiving a response from Ably, @results@ contains an "@HttpPaginatedResponse@@ARTHttpPaginatedResponse@":/docs/api/rest-sdk/types#http-paginated-response containing the @statusCode@ of the response, a @success@ boolean (equivalent to whether the status code is between 200 and 299), @headers@, and an @items@ array containing the current page of results. It supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods, identically to "@PaginatedResult@":/docs/api/rest-sdk/types#paginated-result. - - On failure to obtain a response, @err@ contains an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object with an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an @err@). - -blang[java,ruby,php,python]. - h4. Returns - - On successfully receiving a response from Ably, the returned "@HttpPaginatedResponse@":/docs/api/rest-sdk/types#http-paginated-response contains a @status_code@@statusCode@ and a @success@ boolean, @headers@, and an @items@ array containing the current page of results. It supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods, identically to "@PaginatedResult@":/docs/api/rest-sdk/types#paginated-result. - - Failure to obtain a response will raise an "@AblyException@":/docs/api/realtime-sdk/types#ably-exception. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an exception). - -blang[csharp]. - h4. Returns - - The method is asynchronous and return a Task that has to be awaited to get the result. - - On successfully receiving a response from Ably, the returned "@HttpPaginatedResponse@":/docs/api/rest-sdk/types#http-paginated-response containing the @StatusCode@ and a @Success@ boolean, @Headers@, and an @Items@ array containing the current page of results. "@HttpPaginatedResponse@":/docs/api/rest-sdk/types#http-paginated-response supports pagination using "@NextAsync@":#paginated-result and "@FirstAsync@":#paginated-result methods. - - Failure to obtain a response will raise an "@AblyException@":/docs/api/realtime-sdk/types#ably-exception. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an exception). - -h4. Example - -```[jsall] - const response = await rest.request( - 'get', - '/channels/someChannel/messages', - 3, - { limit: 1, direction: 'forwards' }, - ); - console.log('Success! status code was ' + response.statusCode); - console.log(response.items.length + ' items returned'); - if (response.hasNext()) { - const nextPage = await response.next(); - console.log(nextPage.items.length + ' more items returned'); - } -``` diff --git a/content/partials/rest/_stats.textile b/content/partials/rest/_stats.textile deleted file mode 100644 index 015a9fd82b..0000000000 --- a/content/partials/rest/_stats.textile +++ /dev/null @@ -1,44 +0,0 @@ -h4. Parameters - -- optionsqueryparams := an optional objectHash@ARTStatsQuery@@StatsRequestParams@"@Param@[]":#param array containing the query parameters set of parameters used to specify which statistics are retrieved. If not specified the default parameters will be used - --
&block
:= yields a @PaginatedResult@ object --
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTStats":/docs/api/rest-sdk/types#stats> object or an error - -h4. @options@ parameters@ARTStatsQuery@ properties@StatsRequestParams@ properties@params@ properties - -The following options, as defined in the "REST @/stats@ API":/docs/api/rest-api#stats endpoint, are permitted: - -- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved
__Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__ -- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved
__Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__ -- direction:directionDirection := _backwards_ @:forwards@ or @:backwards@@forwards@ or @backwards@
__Type: @String@@Symbol@@Direction@ enum__ -- limit:limitLimit := _100_ maximum number of stats to retrieve up to 1,000
__Type: @Integer@@Number@__ -- unit:unitUnit := _minute_ @:minute@, @:hour@, @:day@ or @:month@.@minute@, @hour@, @day@ or @month@. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query
__Type: @String@"@StatsIntervalGranularity@":/docs/api/rest-sdk/types#stats-granularity"@ARTStatsGranularity@":#stats-granularity@Symbol@"@StatsIntervalGranularity@":/docs/api/rest-sdk/types#stats-granularity enum__ - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/rest-sdk/types#paginated-result object containing an array of "@Stats@":/docs/api/rest-sdk/types#stats objects. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object. - -blang[objc,swift]. - h4. Callback result - - On success, @result@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@Stats@":/docs/api/rest-sdk/types#stats objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods. - - On failure to retrieve stats, @err@ contains an "@ErrorInfo@":#error-info object with an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation. - -blang[java,ruby,php]. - h4. Returns - - On success, the returned "@PaginatedResult@":#paginated-result encapsulates an array of "@Stats@":/docs/api/rest-sdk/types#stats objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods. - - Failure to retrieve the stats will raise an "@AblyException@":/docs/api/rest-sdk/types#ably-exception - -blang[csharp]. - h4. Returns - - The method is asynchronous and return Task which needs to be awaited. - - On success, the returned "@PaginatedResult@":#paginated-result encapsulates a list of "@Stats@":/docs/api/rest-sdk/types#stats objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@NextAsync@":#paginated-result and "@FirstAsync@":#paginated-result methods. - - Failure to retrieve the stats will raise an "@AblyException@":/docs/api/rest-sdk/types#ably-exception diff --git a/content/partials/shared/_channel_enumeration.textile b/content/partials/shared/_channel_enumeration.textile deleted file mode 100644 index 0396f821f1..0000000000 --- a/content/partials/shared/_channel_enumeration.textile +++ /dev/null @@ -1,28 +0,0 @@ -This enumerates all active channels in the application. This is a paginated API following the same API conventions as other paginated APIs in the "REST interface":/docs/api/rest-sdk. - -This API is intended for occasional use by your servers only; for example, to get an initial set of active channels to be kept up to date using the "channel lifecycle metachannel":/docs/metadata-stats/metadata/subscribe. It is heavily rate-limited: only a single in-flight channel enumeration call is permitted to execute at any one time. Further concurrent calls will be refused with an error with code @42912@. - -Example request: - -bc[sh]. curl https://main.realtime.ably.net/channels \ - -u "{{API_KEY}}" - -This will return either a list of channel names, or a "ChannelDetails":/docs/api/realtime-sdk/channel-metadata#channel-details object depending on what options you've specified. - -The following parameters are supported: - -- limit := _100_ optionally specifies the maximum number of results to return. A limit greater than 1000 is unsupported
__Type: @integer@__ -- prefix := optionally limits the query to only those channels whose name starts with the given prefix
__Type: @string@__ -- by := _id (≥ v3) or value (≤ v2)_ optionally specifies what to return. Use @by=id@ to return only channel names or @by=value@ to return "@ChannelDetails@":/docs/api/realtime-sdk/channel-metadata#channel-details. Using @by=id@ will be much faster, and making very regular @by=value@ enumeration queries can prevent channels from closing down from inactivity. - -The credentials presented with the request must include the @channel-metadata@ permission for the wildcard resource @'*'@. - -Client libraries do not provide a dedicated API to enumerate channels, but make this available using the "request":/docs/api/rest-sdk#request method. When using this, you can simply iterate through the "PaginatedResults":/docs/api/rest-sdk/types#paginated-result to enumerate through the results. - -@Enumeration@ is possible of all channels in an app, by repeated calls to the API, following the @next@ relative link on each successive call, until there is no @next@ relative link. However, this is subject to several limitations: - -* Channels that become active, or become inactive, between the first and last request in the sequence, might or might not appear in the result. The API guarantees that if a channel is continuously active from the time that the first request is made until the time that the last request completes, then it is guaranteed to be present in the result. Similarly, if a channel is continuously inactive between those times then it is guaranteed not to be present in the result; -* Since the state of the cluster may change between successive calls, a pagination sequence may become invalid, in which case the request will respond with an error with code @40011@. In this case, to get a complete result, it is necessary to start the enumeration again from the beginning. Other API options to deal with this possibility maybe provided in later versions of this API. Enumerations that are satisfiable in the first response page do not have this issue. -* The API does not guarantee that the limit will be achieved even if that would be possible. For example, if you specify a limit of 100, the API may return only 37 results together with a @next@ link to get the next page, even if you have more than 37 channels. In the extreme case, the API may return 0 results with a next link. In particular this may be the case if you have a large number of active channels but are specifying a @prefix@ that excludes a significant proportion of them. -* The API does not guarantee that there will be no duplicated results between different pages, especially if a channel is alive in multiple regions. (It does not _currently_ do so, but it may begin to do so with no warning or deprecation period, so your implementation should be able to cope with duplication) -* If you use @by=value@ (which until protocol v3 was the default), just enumerating channels can briefly keep them alive, meaning if you do very regular enumeration you can get a situation where channels never close. diff --git a/content/partials/shared/_channel_metadata.textile b/content/partials/shared/_channel_metadata.textile deleted file mode 100644 index 9f39bca6e4..0000000000 --- a/content/partials/shared/_channel_metadata.textile +++ /dev/null @@ -1,10 +0,0 @@ -This returns a "ChannelDetails":/docs/api/realtime-sdk/channel-metadata#channel-details for the given channel, indicating global "occupancy":/docs/api/rest-sdk/channel-status#occupancy. A side-effect of this request, in the current version of this API, is that it will cause the channel in question to become activated; therefore it is primarily intended to be used in conjunction with the "enumeration API":#enumeration-rest or in situations where the application has another means to know whether or not a given channel is active. - -Example request: - -bc[sh]. curl https://main.realtime.ably.net/channels/ \ - -u "{{API_KEY}}" - -The credentials presented with the request must include the @channel-metadata@ permission for the channel in question. - -Client libraries currently do not support this API, but it is usable via the generic "request API":/docs/api/rest-sdk#request. diff --git a/content/partials/shared/_channel_namespaces.textile b/content/partials/shared/_channel_namespaces.textile deleted file mode 100644 index 857a9a2bf5..0000000000 --- a/content/partials/shared/_channel_namespaces.textile +++ /dev/null @@ -1,20 +0,0 @@ -One or more channel rules may be configured for an app in your "dashboard":https://ably.com/dashboard. These are rules which apply to a channel based on its 'namespace'. The namespace is the first colon-delimited segment of its name (from the start, up to and including, the last character before the @:@). If the channel name contains no colon, the namespace is the entire channel name. - -For example, the following channels are all part of the "public" namespace: - -* @public@ -* @public:events@ -* @public:news:americas@ - -*Note* that wildcards are not supported in channel namespaces. - -The namespace attributes that can be configured are: - -- Persist last message := if enabled, the very last message published on a channel will be stored for an entire year, retrievable using the "channel rewind mechanism":/docs/channels/options/rewind by attaching to the channel with @rewind=1@. If you send multiple messages atomically in a single protocol message, for example with @publish([{...}, {...}, {...}])@, you would receive all of them as one message. Only messages are stored, not presence messages. This last message storage is not accessible using the normal history API, only through rewind. **Please note that for the message stored, an additional message is deducted from your monthly allocation.** -- Persist all messages := if enabled, all messages within this namespace will be stored according to the storage rules for your account (24 hours for free accounts). You can access stored messages via the "history API":/docs/storage-history/history. **Please note that for each message stored, an additional message is deducted from your monthly allocation.** -- Identified := if enabled, clients will not be permitted to use (including to attach, publish, or subscribe) matching channels unless they are "identified":/docs/auth/identified-clients (they have an assigned client ID). Anonymous clients are not permitted to join these channels. Find out more about "authenticated and identified clients":/docs/auth/identified-clients. -- TLS only := if enabled, only clients who have connected to Ably over TLS will be allowed to use matching channels. By default all of Ably's client libraries use TLS when communicating with Ably over REST or when using our Realtime transports such as Websockets. -- Push notifications enabled := If checked, publishing messages with a push payload in the extras field is permitted and can trigger the delivery of a push notification to registered devices for the channel. Find out more about "push notifications":/docs/push. -- Message interactions enabled := If enabled, messages received on a channel will contain a unique @timeserial@ that can be referenced by later messages for use with message interactions. Find out more about "message interactions":/docs/channels/messages#message-interactions. - -Key or token capabilities can also specify access rights based on channel namespace. Find out more about "authentication":/docs/auth. diff --git a/content/partials/shared/_presence_states.textile b/content/partials/shared/_presence_states.textile deleted file mode 100644 index 43794c0a1d..0000000000 --- a/content/partials/shared/_presence_states.textile +++ /dev/null @@ -1,11 +0,0 @@ -Whenever a member enters or leaves a channel, or updates "their member data":#member-data, a presence event is emitted to all presence subscribers on that channel. Subscribing to presence events makes it incredibly easy to build an app that shows, in real time, any changes to clients connected to Ably and present on a channel. - -The following presence events are emitted: - -- :enterPresenceAction.ENTERAction.ENTEREnterenter := A new member has entered the channel - -- :leavePresenceAction.LEAVEAction.LEAVELeaveleave := A member who was present has now left the channel. This may be a result of an explicit request to leave or implicitly when detaching from the channel. Alternatively, if a member's connection is abruptly disconnected and they do not resume their connection within a minute, Ably treats this as a leave event as the client is no longer present - -- :updatePresenceAction.UPDATEAction.UPDATEUpdateupdate := An already present member has updated their "member data":#member-data. Being notified of member data updates can be very useful, for example, it can be used to update the status of a user when they are typing a message - -- :presentPresenceAction.PRESENTAction.PRESENTPresentpresent := When subscribing to presence events on a channel that already has members present, this event is emitted for every member already present on the channel before the subscribe listener was registered diff --git a/content/partials/shared/_token_auth_methods.textile b/content/partials/shared/_token_auth_methods.textile deleted file mode 100644 index d6d23b4a60..0000000000 --- a/content/partials/shared/_token_auth_methods.textile +++ /dev/null @@ -1,11 +0,0 @@ -- authCallbackAuthCallbackauth_callback:auth_callback := A functionfunction with the form @function(tokenParams, callback(err, tokenOrTokenRequest))@@TokenCallback@ instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed "@TokenRequest@":/docs/api/realtime-sdk/types#token-request ; a "@TokenDetails@":/docs/api/realtime-sdk/types#token-details (in JSON format); an "Ably JWT":/docs/api/realtime-sdk/authentication#ably-jwt. See "our authentication documentation":/docs/auth for details of the Ably TokenRequest format and associated API calls.
__Type: @Callable@@TokenCallback@@Proc@@Func>@__ - -- authUrlAuthUrl:auth_urlauth_url := A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed "@TokenRequest@":/docs/api/realtime-sdk/types#token-request ; a "@TokenDetails@":/docs/api/realtime-sdk/types#token-details (in JSON format); an "Ably JWT":/docs/api/realtime-sdk/authentication#ably-jwt. For example, this can be used by a client to obtain signed Ably TokenRequests from an application server.
__Type: @String@@Uri@@NSURL@__ - -- authMethodAuthMethodauth_method:auth_method := _@GET@@:get@_ The HTTP verb to use for the request, either @GET@@:get@ or @POST@@:post@
__Type: @String@@Symbol@@HttpMethod@__ - -- authHeadersAuthHeadersauth_headers:auth_headers := A set of key value pair headers to be added to any request made to the @authUrl@@AuthUrl@. Useful when an application requires these to be added to validate the request or implement the response. If the @authHeaders@ object contains an @authorization@ key, then @withCredentials@ will be set on the xhr request.
__Type: @Object@@Dict@@Hash@@Associative Array@@Param []@@Dictionary@@Map@__ - -- authParamsAuthParams:auth_paramsauth_params := A set of key value pair params to be added to any request made to the @authUrl@@AuthUrl@. When the @authMethod@@AuthMethod@ is @GET@, query params are added to the URL, whereas when @authMethod@@AuthMethod@ is @POST@, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.
__Type: @Object@@Hash@@Associative Array@@Param[]@@Dictionary@@NSArray@@[NSURLQueryItem]/Array@@Map@__ - -- tokenDetailsTokenDetailstoken_details:token_details := An authenticated "@TokenDetails@":/docs/api/realtime-sdk/types#token-details object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as @authUrl@@AuthUrl@@:auth_url@@auth_url@ or @authCallback@AuthCallback@auth_callback@@:auth_callback@. Use this option if you wish to use Token authentication. Read more about "Token authentication":/docs/auth/token
__Type: @TokenDetails@__ diff --git a/content/partials/types/_ably_exception.textile b/content/partials/types/_ably_exception.textile deleted file mode 100644 index d46fdcb9f9..0000000000 --- a/content/partials/types/_ably_exception.textile +++ /dev/null @@ -1,8 +0,0 @@ -An @AblyException@ is an exception encapsulating error information containing an Ably-specific error code and generic status code, where applicable. - -h4. - default: Properties - java: Members - ruby: Attributes - -- errorInfoErrorInfo := "@ErrorInfo":/docs/api/realtime-sdk/types#error-info corresponding to this exception, where applicable
__Type: @ErrorInfo@__ diff --git a/content/partials/types/_auth_options.textile b/content/partials/types/_auth_options.textile deleted file mode 100644 index a5ac1891c3..0000000000 --- a/content/partials/types/_auth_options.textile +++ /dev/null @@ -1,28 +0,0 @@ -blang[jsall]. - @AuthOptions@ is a plain JavaScript object and is used when making "authentication":/docs/auth requests. If passed in, an @authOptions@ object will be used instead of (as opposed to supplementing or being merged with) the default values given when the library was instantiated. The following attributes are supported: - -blang[ruby]. - @AuthOptions@ is a Hash object and is used when making "authentication":/docs/auth requests. These options will supplement or override the corresponding options given when the library was instantiated. The following key symbol values can be added to the Hash: - -blang[python]. - @AuthOptions@ is a Dict and is used when making "authentication":/docs/auth requests. These options will supplement or override the corresponding options given when the library was instantiated. The following key symbol values can be added to the Dict: - -blang[php]. - @AuthOptions@ is an Associative Array and is used when making "authentication":/docs/auth requests. These options will supplement or override the corresponding options given when the library was instantiated. The following named keys and values can be added to the Associative Array: - -blang[java,swift,objc,go]. - @ART@@AuthOptions@ is used when making "authentication":/docs/auth requests. These options will supplement or override the corresponding options given when the library was instantiated. - -h4. - default: Properties - java: Members - ruby: Attributes - Python: Attributes - -<%= partial partial_version('shared/_token_auth_methods') %> - -- keyKey:keykey := Optionally the "API key":/docs/auth#api-key to use can be specified as a full key string; if not, the API key passed into "@ClientOptions@":#client-options when instancing the Realtime or REST library is used
__Type: @String@__ - -- queryTimeQueryTime:query_timequery_time := _false_ If true, the library will query the Ably servers for the current time when "issuing TokenRequests":/docs/auth/token instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably "TokenRequests":/docs/auth/token, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an "NTP daemon":https://en.wikipedia.org/wiki/Ntpd . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
__Type: @Boolean@__ - -- tokenToken:token := An authenticated token. This can either be a "@TokenDetails@":/docs/api/realtime-sdk/types#token-details object, a "@TokenRequest@":/docs/api/realtime-sdk/types#token-request object, or token string (obtained from the @token@@Token@ property of a "@TokenDetails@":/docs/api/realtime-sdk/types#token-details component of an Ably TokenRequest response, or a "JSON Web Token":https://tools.ietf.org/html/rfc7519 satisfying "the Ably requirements for JWTs":/docs/auth/token#jwt). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as @authUrl@AuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about "Token authentication":/docs/auth/token
__Type: @String@, @TokenDetails@ or @TokenRequest@__ diff --git a/content/partials/types/_base_ably_exception.textile b/content/partials/types/_base_ably_exception.textile deleted file mode 100644 index 346b9f0130..0000000000 --- a/content/partials/types/_base_ably_exception.textile +++ /dev/null @@ -1,13 +0,0 @@ -A @BaseAblyException@an @AblyException@ is an exception encapsulating error information containing an Ably-specific error code and generic status code, where applicable. - -h4. - default: Properties - java: Members - ruby: Attributes - python: Attributes - -- codeCode := Ably error code (see "ably-common/protocol/errors.json":https://github.com/ably/ably-common/blob/main/protocol/errors.json)
__Type: @Integer@__ - -- statusCodestatus_codeStatusCode := HTTP Status Code corresponding to this error, where applicable
__Type: @Integer@__ - -- messageMessage := Additional message information, where available
__Type: @String@__ diff --git a/content/partials/types/_batch_presence_failure_result.textile b/content/partials/types/_batch_presence_failure_result.textile deleted file mode 100644 index cf3995a7cf..0000000000 --- a/content/partials/types/_batch_presence_failure_result.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @BatchPresenceFailureResult@ contains information about the result of an unsuccessful batch presence request for a single channel. - -h4. - default: Properties - -- channel := The channel name the presence state failed to be retrieved for
__Type: @String@__ - -- error := Describes the reason for which presence state could not be retrieved for the channel as an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object
__Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__ diff --git a/content/partials/types/_batch_presence_success_result.textile b/content/partials/types/_batch_presence_success_result.textile deleted file mode 100644 index 4be5e5e2bf..0000000000 --- a/content/partials/types/_batch_presence_success_result.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @BatchPresenceSuccessResult@ contains information about the result of a successful batch presence request for a single channel. - -h4. - default: Properties - -- channel := The channel name the presence state was retrieved for
__Type: @String@__ - -- presence := An array of "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message describing members present on the channel
__Type: "@PresenceMessage[]@":/docs/api/realtime-sdk/types#presence-message diff --git a/content/partials/types/_batch_publish_failure_result.textile b/content/partials/types/_batch_publish_failure_result.textile deleted file mode 100644 index 2f7972cc1c..0000000000 --- a/content/partials/types/_batch_publish_failure_result.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @BatchPublishFailureResult@ contains information about the result of unsuccessful publishes to a channel requested by a single "@BatchPublishSpec@":/docs/api/realtime-sdk/types#batch-publish-spec. - -h4. - default: Properties - -- channel := The name of the channel the message(s) failed to be published to
__Type: @String@__ - -- error := Describes the reason for which the message(s) failed to publish to the channel as an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object
__Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__ diff --git a/content/partials/types/_batch_publish_spec.textile b/content/partials/types/_batch_publish_spec.textile deleted file mode 100644 index 44b3016b1a..0000000000 --- a/content/partials/types/_batch_publish_spec.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @BatchPublishSpec@ describes the messages that should be published by a batch publish operation, and the channels to which they should be published. - -h4. - default: Properties - -- channels := The names of the channels to publish the @messages@ to
__Type: @String[]@__ - -- messages := An array of "@Message@":/docs/api/realtime-sdk/types#message objects
__Type: "@Message[]@":/docs/api/realtime-sdk/types#message__ diff --git a/content/partials/types/_batch_publish_success_result.textile b/content/partials/types/_batch_publish_success_result.textile deleted file mode 100644 index ebde876657..0000000000 --- a/content/partials/types/_batch_publish_success_result.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @BatchPublishSuccessResult@ contains information about the result of successful publishes to a channel requested by a single "@BatchPublishSpec@":/docs/api/realtime-sdk/types#batch-publish-spec. - -h4. - default: Properties - -- channel := The name of the channel the message(s) was published to
__Type: @String@__ - -- messageId := A unique ID prefixed to the @Message.id@ of each published message
__Type: @String@__ diff --git a/content/partials/types/_batch_result.textile b/content/partials/types/_batch_result.textile deleted file mode 100644 index 0f38217513..0000000000 --- a/content/partials/types/_batch_result.textile +++ /dev/null @@ -1,10 +0,0 @@ -A @BatchResult@ contains information about the results of a batch operation. - -h4. - default: Properties - -- successCount := The number of successful operations in the request
__Type: @Number@__ - -- failureCount := The number of unsuccessful operations in the request
__Type: @Number@__ - -- messages := An array of results for the batch operation (for example, an array of "@BatchPublishSuccessResult@":/docs/api/realtime-sdk/types#batch-publish-success-result or "@BatchPublishFailureResult@":/docs/api/realtime-sdk/types#batch-publish-failure-result for a channel batch publish request)
__Type: Object[]__ diff --git a/content/partials/types/_channel_details.textile b/content/partials/types/_channel_details.textile deleted file mode 100644 index 1dd8925635..0000000000 --- a/content/partials/types/_channel_details.textile +++ /dev/null @@ -1,53 +0,0 @@ -h3(#channel-details). ChannelDetails - -@ChannelDetails@ is an object returned when requesting or receiving "channel metadata":/docs/metadata-stats/metadata. It contains information on the channel itself, along with the current state of the channel in the "ChannelStatus":#channel-status object. - -- channelId := the required name of the channel including any qualifier, if any
__Type: @string@__ -- region := in events relating to the activity of a channel in a specific region, this optionally identifies the region
__Type: @string@__ -- isGlobalMaster := in events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channel
__Type: @boolean@__ -- status := an optional "@ChannelStatus@":#channel-status instance
__Type: "ChannelStatus":#channel-status__ - -The following is an example of a @ChannelDetails@ JSON object: - -```[json] - { - "channelId": "foo", - "status": { - "isActive": true, - "occupancy": { - "metrics": { - "connections": 1, - "publishers": 1, - "subscribers": 1, - "presenceConnections": 1, - "presenceMembers": 0, - "presenceSubscribers": 1, - "objectPublishers": 1, - "objectSubscribers": 1 - } - } - } - } -``` - -h3(#channel-status). ChannelDetails.ChannelStatus - -@ChannelStatus@ is contained within the "@ChannelDetails@":#channel-details object, and optionally contains an "Occupancy":#occupancy object. - -- isActive := a required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity
__Type: @boolean@__ -- occupancy := an optional "@Occupancy@":#occupancy instance indicating the occupancy of the channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
__Type: "Occupancy":#occupancy__ - -h3(#occupancy). ChannelDetails.ChannelStatus.Occupancy - -Occupancy is optionally contained within the "@ChannelStatus@":#channel-status object, and contains metadata relating to the occupants of the channel. This is usually contained within the @occupancy@ attribute of the "@ChannelStatus@":#channel-status object. - -The @occupancy@ attribute contains the @metrics@ attribute, which contains the following members: - -- connections := the number of connections
__Type: @integer@__ -- publishers := the number of connections attached to the channel that are authorised to publish
__Type: @integer@__ -- subscribers := the number of connections attached that are authorised to subscribe to messages
__Type: @integer@__ -- presenceSubscribers := the number of connections that are authorised to subscribe to presence messages
__Type: @integer@__ -- presenceConnections := the number of connections that are authorised to enter members into the presence channel
__Type: @integer@__ -- presenceMembers := the number of members currently entered into the presence channel
__Type: @integer@__ -- objectPublishers := the number of connections that are authorised to publish updates to objects on the channel
__Type: @integer@__ -- objectSubscribers := the number of connections that are authorised to subscribe to objects on the channel
__Type: @integer@__ diff --git a/content/partials/types/_channel_event.textile b/content/partials/types/_channel_event.textile deleted file mode 100644 index 296c0409e2..0000000000 --- a/content/partials/types/_channel_event.textile +++ /dev/null @@ -1,132 +0,0 @@ -blang[jsall]. - @ChannelEvent@ is a String that can be emitted as an event on the @Channel@ object; either a "@ChannelState@":/docs/channels/states or an @update@ event. - - ```[javascript] - var ChannelEvents = [ - 'initialized', - 'attaching', - 'attached', - 'detaching', - 'detached', - 'failed', - 'suspended', - 'update' - ] - ``` - -blang[java]. - @io.ably.lib.realtime.ChannelEvent@ is an enum representing all the events that can be emitted be the @Channel@; either a "@ChannelState@":/docs/channels/states or an @update@ event. - - ```[java] - public enum ChannelEvent { - initialized, // 0 - attaching, // 1 - attached, // 2 - detaching, // 3 - detached, // 4 - failed // 5 - update // 6 - } - ``` - -blang[csharp]. - @IO.Ably.Realtime.ChannelEvent@ is an enum representing all the events that can be emitted be the @Channel@; either a "@ChannelState@":/docs/channels/states or an @Update@ event. - - ```[csharp] - public enum ChannelEvent - { - Initialized = 0, - Attaching = 1, - Attached = 2, - Detaching= 3, - Detached = 4, - Failed = 5, - Update = 6 - }; - ``` - -blang[ruby]. - @Ably::Realtime::Channel::EVENT@ is an enum-like value representing all the events that can be emitted be the @Channel@; either a "@ChannelState@":/docs/channels/states or an @:update@ event. @EVENT@ can be represented interchangeably as either symbols or constants. - - h4. Symbol states - - ```[ruby] - :initialized # => 0 - :attaching # => 1 - :attached # => 2 - :detaching # => 3 - :detached # => 4 - :failed # => 5 - :update # => 6 - ``` - - h4. Constant states - - ```[ruby] - Channel::EVENT.Initialized # => 0 - Channel::EVENT.Attaching # => 1 - Channel::EVENT.Attached # => 2 - Channel::EVENT.Detaching # => 3 - Channel::EVENT.Detached # => 4 - Channel::EVENT.Failed # => 5 - Channel::EVENT.Update # => 6 - ``` - -blang[objc,swift]. - @ARTChannelEvent@ is the enum emitted as the event in @ARTRealtimeChannel.on@; either a "@ChannelState@":/docs/api/realtime-sdk/channels#channel-state or an @Update@ event. - - ```[objc] - typedef NS_ENUM(NSUInteger, ARTChannelEvent) { - ARTChannelEventInitialized, - ARTChannelEventAttaching, - ARTChannelEventAttached, - ARTChannelEventDetaching, - ARTChannelEventDetached, - ARTChannelEventFailed, - ARTChannelEventUpdate - }; - ``` - - ```[swift] - enum ARTChannelEvent : UInt { - case Initialized - case Attaching - case Attached - case Detaching - case Detached - case Failed - case Update - } - ``` - -blang[go]. - @ChannelEvent@ is a String that can be emitted as an event on the @Channel@ object; either a "@ChannelState@":/docs/channels/states or an @update@ event. - - ```[go] - const ( - StateChanInitialized = 256 - StateChanConnecting = 512 - StateChanConnected = 1024 - StateChanDisconnected = 2048 - StateChanSuspended = 4096 - StateChanClosing = 8192 - StateChanClosed = 16384 - StateChanFailed = 32768 - ) - ``` - -blang[flutter]. - @ably.ChannelEvent@ is an enum representing all the events that can be emitted be the @Channel@; either a "@ChannelState@":/docs/channels/states or an @update@ event. - - ```[flutter] - enum ChannelEvent { - initialized, - attaching, - attached, - detaching, - detached, - suspended, - failed, - update - } - ``` diff --git a/content/partials/types/_channel_options.textile b/content/partials/types/_channel_options.textile deleted file mode 100644 index 89b3653d72..0000000000 --- a/content/partials/types/_channel_options.textile +++ /dev/null @@ -1,47 +0,0 @@ -Channel options are used for setting "channel parameters":/docs/channels/options and "configuring encryption":/docs/channels/options/encryption. - -blang[jsall]. - @ChannelOptions@, a plain JavaScript object, may optionally be specified when instancing a "@Channel@":/docs/channels, and this may be used to specify channel-specific options. The following attributes can be defined on the object: - -blang[ruby]. - @ChannelOptions@, a Hash object, may optionally be specified when instancing a "@Channel@":/docs/channels, and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash: - -blang[php]. - @ChannelOptions@, an Associative Array, may optionally be specified when instancing a "@Channel@":/docs/channels, and this may be used to specify channel-specific options. The following named keys and values can be added to the Associated Array: - -blang[java,swift,objc,go]. - @ART@@io.ably.lib.types.@@ChannelOptions@ may optionally be specified when instancing a "@Channel@":/docs/channels, and this may be used to specify channel-specific options. - -blang[csharp]. - @IO.Ably.ChannelOptions@ may optionally be specified when instancing a "@Channel@":/docs/channels, and this may be used to specify channel-specific options. - -h4. - default: Properties - java: Members - ruby: Attributes - -blang[default]. - - :cipherCipherParamscipher := Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See "an example":/docs/channels/options/encryption
__Type: "@CipherParams@":/docs/api/realtime-sdk/encryption#cipher-params or an options object containing at a minimum a @key@ or a @Param[]@ list containing at a minimum a @key@ or an options hash containing at a minimum a @key@ or an Associative Array containing at a minimum a @key@__ - - -blang[jsall,java,swift,objc,csharp]. - - paramsParams := Optional "parameters":/docs/channels/options which specify behaviour of the channel.
__Type: @Map@@JSON Object@__ - - cipherCipherParams := Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See "an example":/docs/api/realtime-sdk/encryption#getting-started
__Type: "@CipherParams@":/docs/api/realtime-sdk/encryption#cipher-params or an options object containing at a minimum a @key@ or a @Param[]@ list containing at a minimum a @key@ or an options hash containing at a minimum a @key@ or an Associative Array containing at a minimum a @key@__ - -blang[java]. - h4. Static methods - - h6(#with-cipher-key). withCipherKey - - bq(definition). static ChannelOptions.withCipherKey(Byte[] or String key) - - A helper method to generate a @ChannelOptions@ for the simple case where you only specify a key. - - h4. Parameters - - - key := A binary @Byte[]@ array or a base64-encoded @String@. - - h4. Returns - - On success, the method returns a complete @ChannelOptions@ object. Failure will raise an "@AblyException@":/docs/api/realtime-sdk/types#ably-exception. - diff --git a/content/partials/types/_channel_state.textile b/content/partials/types/_channel_state.textile deleted file mode 100644 index 9840d06c92..0000000000 --- a/content/partials/types/_channel_state.textile +++ /dev/null @@ -1,137 +0,0 @@ -blang[jsall]. - @ChannelState@ is a String with a value matching any of the "@Realtime Channel@ states":/docs/channels/states. - - ```[javascript] - var ChannelStates = [ - 'initialized', - 'attaching', - 'attached', - 'detaching', - 'detached', - 'failed', - 'suspended' - ] - ``` - -blang[java]. - @io.ably.lib.realtime.ChannelState@ is an enum representing all the "@Realtime Channel@ states":/docs/channels/states. - - ```[java] - public enum ChannelState { - initialized, // 0 - attaching, // 1 - attached, // 2 - detaching, // 3 - detached, // 4 - failed // 5 - } - ``` - -blang[csharp]. - @IO.Ably.Realtime.ChannelState@ is an enum representing all the "@Realtime Channel@ states":/docs/channels/states. - - ```[csharp] - public enum ChannelState - { - Initialized = 0, - Attaching = 1, - Attached = 2, - Detaching= 3, - Detached = 4, - Failed = 5 - }; - ``` - -blang[ruby]. - @Ably::Realtime::Channel::STATE@ is an enum-like value representing all the "@Realtime Channel@ states":/docs/channels/states. @STATE@ can be represented interchangeably as either symbols or constants. - - h4. Symbol states - - ```[ruby] - :initialized # => 0 - :attaching # => 1 - :attached # => 2 - :detaching # => 3 - :detached # => 4 - :failed # => 5 - ``` - - h4. Constant states - - ```[ruby] - Channel::STATE.Initialized # => 0 - Channel::STATE.Attaching # => 1 - Channel::STATE.Attached # => 2 - Channel::STATE.Detaching # => 3 - Channel::STATE.Detached # => 4 - Channel::STATE.Failed # => 5 - ``` - - h4. Example usage - - ```[ruby] - # Example with symbols - channel.on(:attached) { ... } - - # Example with constants - channel.on(Ably::Realtime::Channel::STATE.Attached) { ... } - - # Interchangeable - Ably::Realtime::Channel::STATE.Attached == :attached # => true - ``` - -blang[objc,swift]. - @ARTRealtimeChannelState@ is an enum representing all the "@Realtime Channel@ states":/docs/channels/states. - - ```[objc] - typedef NS_ENUM(NSUInteger, ARTRealtimeChannelState) { - ARTRealtimeChannelInitialized, - ARTRealtimeChannelAttaching, - ARTRealtimeChannelAttached, - ARTRealtimeChannelDetaching, - ARTRealtimeChannelDetached, - ARTRealtimeChannelFailed - }; - ``` - - ```[swift] - public enum ARTRealtimeChannelState : UInt { - case Initialized - case Attaching - case Attached - case Detaching - case Detached - case Failed - } - ``` - -blang[go]. - @ChannelState@ is a string representing all the "channel states":/docs/channels/states - - ```[go] - const ( - StateChanInitialized = 256 - StateChanConnecting = 512 - StateChanConnected = 1024 - StateChanDisconnected = 2048 - StateChanSuspended = 4096 - StateChanClosing = 8192 - StateChanClosed = 16384 - StateChanFailed = 32768 - ) - ``` - -blang[flutter]. - @ably.ChannelState@ is an enum representing all the "@Realtime Channel@ states":/docs/channels/states. - - ```[flutter] - enum ChannelState { - initialized, - attaching, - attached, - detaching, - detached, - suspended, - failed - } - ``` diff --git a/content/partials/types/_channel_state_change.textile b/content/partials/types/_channel_state_change.textile deleted file mode 100644 index 53eb50f901..0000000000 --- a/content/partials/types/_channel_state_change.textile +++ /dev/null @@ -1,9 +0,0 @@ -A @Ably::Models::ChannelStateChange@ChannelStateChangeARTRealtimeChannelStateChange is a type encapsulating state change information emitted by the "@Channel@":/docs/channels object. See "@Channel#on@":/docs/api/realtime-sdk/channels#on to register a listener for one or more events. - -h4. Attributes - -- currentCurrent := the new current state
__Type: "@ChannelState@Channel::STATE@":/docs/api/realtime-sdk/types#channel-state__ -- previousPrevious := the previous state. (for the @update@ event, this will be equal to the @current@ state)
__Type: "@ChannelState@Channel::STATE@":/docs/api/realtime-sdk/types#channel-state__ -- eventEvent := the event that triggered this state change
__Type: "@ChannelEvent@Channel::EVENT@":/docs/api/realtime-sdk/types#channel-event__ -- reasonReason := an "@ErrorInfo@":#error-info containing any information relating to the transition
__Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__ -- resumedResumed := a boolean indicated whether message continuity on this channel is preserved, see "Nonfatal channel errors":/docs/channels#non-fatal-errors for more info.
__Type: Boolean__ diff --git a/content/partials/types/_channel_state_listener.textile b/content/partials/types/_channel_state_listener.textile deleted file mode 100644 index 751ca88b45..0000000000 --- a/content/partials/types/_channel_state_listener.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @io.ably.lib.realtime.ChannelStateListener@ is an interface allowing a client to be notified of "channel state changes":/docs/api/realtime-sdk/types#channel-state-change for a "@Channel@":/docs/channels - -```[java] - public interface ChannelStateListener { - // Called when the channel state changes - public void onChannelStateChanged(ChannelStateChange stateChange, ErrorInfo reason); - } -``` diff --git a/content/partials/types/_cipher_params.textile b/content/partials/types/_cipher_params.textile deleted file mode 100644 index b27c210ec6..0000000000 --- a/content/partials/types/_cipher_params.textile +++ /dev/null @@ -1,16 +0,0 @@ -A @CipherParams@ contains configuration options for a channel cipher, including algorithm, mode, key length and key. Ably client libraries currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128. - -Individual client libraries may support either instancing a @CipherParams@ directly, using "@Crypto.getDefaultParams()@":/docs/api/realtime-sdk/encryption#get-default-params"@Crypto.GetDefaultParams()@":/docs/api/realtime-sdk/encryption#get-default-params"@Crypto.get_default_params()@":/docs/api/realtime-sdk/encryption#get-default-params, or generating one automatically when initializing a channel, as in "this example":/docs/channels/options/encryption. - -h4. - default: Properties - java: Members - ruby: Attributes - --
keyKey:key
:= A binary (@byte[]@@ArrayBuffer@ or @Uint8Array@@Buffer@byte array@NSData@) or base64-encoded @NS@@String@ containing the secret key used for encryption and decryption - -- algorithm:algorithmAlgorithm := _AES_ The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES"
__Type: @String@__ -- key_length:key_lengthkeyLengthKeyLength := _256_ The key length in bits of the cipher, either 128 or 256
__Type: @Integer@__ -- mode:modeMode := _CBC_ The cipher mode
__Type: @String@@CipherMode@__ - --
keySpec
:= A @KeySpec@ for the cipher key
__Type: @SecretKeySpec@__ diff --git a/content/partials/types/_client_options.textile b/content/partials/types/_client_options.textile deleted file mode 100644 index d3f0e15ee7..0000000000 --- a/content/partials/types/_client_options.textile +++ /dev/null @@ -1,68 +0,0 @@ -h4. - default: Properties - java: Members - ruby: Attributes - python: Keyword arguments - -- keyKey:key := The full key string, as obtained from the "application dashboard":https://ably.com/dashboard. Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about "Basic authentication":/docs/auth/basic
__Type: @String@__ - -- tokenToken:token := An authenticated token. This can either be a "@TokenDetails@":/docs/api/realtime-sdk/types#token-details object, a "@TokenRequest@":/docs/api/realtime-sdk/types#token-request object, or token string (obtained from the @token@@Token@ property of a "@TokenDetails@":/docs/api/realtime-sdk/types#token-details component of an Ably TokenRequest response, or a "JSON Web Token":https://tools.ietf.org/html/rfc7519 satisfying "the Ably requirements for JWTs":/docs/auth/token#jwt). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as @authUrl@@AuthUrl@:auth_urlauth_url or @authCallback@@AuthCallback@@auth_callback@@:auth_callback@. Read more about "Token authentication":/docs/auth/token
__Type: @String@, @TokenDetails@ or @TokenRequest@__ - -<%= partial partial_version('shared/_token_auth_methods') %> - -- tlsTls:tls := _true_ A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. The JavaScript library uses the TLS version supported by the browser environment.In Node.js, the TLS version is determined by the Node.js runtime version. "Find out more about TLS":/docs/channels/options/encryption#tls
__Type: @Boolean@__ - -- clientIdClientIdclient_id:client_id := A client ID, used for identifying this client when publishing messages or for presence purposes. The @clientId@@client_id@@ClientId@ can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a @clientId@@client_id@@ClientId@ may also be implicit in a token used to instantiate the library; an error will be raised if a @clientId@@client_id@ specified here conflicts with the @clientId@@client_id@@ClientId@ implicit in the token. "Find out more about client identities":/docs/auth/identified-clients
__Type: @String@__ - -- useTokenAuthUseTokenAuthuse_token_auth:use_token_auth := _false_ When true, forces "Token authentication":/docs/auth/token to be used by the library. Please note that if a @client_id@@clientId@ is not specified in the "@ClientOptions@":/docs/api/realtime-sdk/types#client-options or "@TokenParams@":/docs/api/realtime-sdk/types#token-params, then the Ably Token issued will be "anonymous":https://faqs.ably.com/authenticated-and-identified-clients.
__Type: @Boolean@__ - -- endpointEndpoint:endpoint := _nullNullNonenil_ Enables "enterprise customers":https://ably.com/pricing to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our "platform customization guide":/docs/platform/account/enterprise-customization for more details.
__Type: @String@__ - -- environmentEnvironment:environment := _nullNullNonenil_ Deprecated, use @endpoint@. Enables "enterprise customers":https://ably.com/pricing to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our "platform customization guide":/docs/platform/account/enterprise-customization for more details.
__Type: @String@__ - -- idempotentRestPublishingIdempotentRestPublishing:idempotent_rest_publishing := _false_ When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.
__Type: @Boolean@__ - -- fallbackHostsFallbackHostsfallback_hosts:fallback_hosts := _@[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]@_ An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the "fallback host functionality":https://faqs.ably.com/routing-around-network-and-dns-issues is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
__Type: @String []@__ - -- transportParamsTransportParamstransport_params:transport_params := Optional. Can be used to pass in arbitrary connection parameters, such as "@heartbeatInterval@":/docs/connect#heartbeats and "@remainPresentFor@":/docs/presence-occupancy/presence#unstable-connections
__Type: @Object@@Dict@@Hash@@Associative Array@@Param []@@Dictionary@@Map@__ - -blang[jsall]. - - logLevel := A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output).
__Type: @Integer@__ - - - logHandler := A function to handle each line of the library's log output. If @logHandler@ is not specified, @console.log@ is used.
__Type: @Callable@__ - - - transports := An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: @web_socket@, @xhr_polling@.The transports available in the Node.js client library are: @web_socket@, @xhr_polling@, @comet@.
__Type: @String []@__ - -blang[java]. - - logLevel := _5_ A number controlling the verbosity of the output from 2 (maximum, verbose) to 6 (errors only). A special value of 99 will silence all logging. Note that the @logLevel@ is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently. See "the logging section of the java library README":https://github.com/ably/ably-java/#logging for more details.
__Type: @Integer@__ - - - logHandler := _@System.out PrintStream@_ A @LogHandler@ interface can be specified to handle each line of log output. If @logHandler@ is not specified, @System.out@ is used. Note that the @logHandler@ is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently. See "the logging section of the java library README":https://github.com/ably/ably-java/#logging for more details.
__Type: PrintStream__ - -blang[csharp]. - To set the log level and custom logger sink when using the .NET library, configure the static @IO.Ably.Logger@ class or specify the @ClientOptions@: - - - LogLevel := _@Error@_ This is an enum controlling the verbosity of the output from @Debug@ (maximum) to @Error@ (errors only). A special value of @None@ will silence all logging. Note that the @LogLevel@ is a static variable in the library and will thus not act independently between library instances.
__Type: @Enum@__ - - - LoggerSink := _@IO.Ably.DefaultLoggerSink@_ The default ILoggerSink outputs messages to the debug console. This property allows the user to pipe the log messages to their own logging infrastructure. - -blang[go]. - - LogLevel := _@LogError@_ This is an enum controlling the verbosity of the output from @LogDebug@ (maximum) to @LogError@ (errors only). A special value of @LogNone@ will silence all logging. Note that the @LogLevel@ is a static variable in the library and will thus not act independently between library instances.
__Type: @Enum@__ - -blang[objc,swift]. - - logLevel := _ARTLogLevelWarn_ An enum controlling the verbosity of the output from @ARTLogLevelVerbose@ to @ARTLogLevelNone@. A special value of 99 will silence all logging.
__Type: @ARTLogLevel@__ - - - logHandler := A @ARTLog@ object can be specified to handle each line of log output. If @logHandler@ is not specified, a default @ARTLog@ instance is used.
__Type: @ARTLog *@__ - -blang[ruby]. - - :log_level :=_@:error@_ Log level for the standard Logger that outputs to @STDOUT@. Can be set to @:fatal@, @:error@, @:warn@, @:info@, @:debug@ or @:none@. Alternatively a "@Logger@ severity constant":http://ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html#class-Logger-label-Description can be specified.
__Type: @Symbol@, "@Logger::SEVERITY@":http://ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html#class-Logger-label-Description__ - - - :logger := _@STDOUT Logger@_ A "Ruby @Logger@":http://ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html compatible object to handle each line of log output. If @logger@ is not specified, @STDOUT@ is used.
__Type: "Ruby @Logger":http://ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html__ - -blang[php]. - - logLevel :=_@Log::WARNING@_ A number controlling the verbosity of the output from 1 (minimum, errors only) to 4 (most verbose);
__Type: @Integer@__ - - - logHandler := _@console.log@_ A function to handle each line of log output. If handler is not specified, @console.log@ is used. Note that the log level and log handler have global scope in the library and will therefore not act independently between library instances when multiple library instances exist concurrently.
__Type: @Function@__ - -- useBinaryProtocolUseBinaryProtocoluse_binary_protocol:use_binary_protocol := _false_ If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON)_true_ If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supportedNote: The binary protocol is currently not supported in Swiftin Objective-Cin PHP. Find out more about the "benefits of binary encoding":https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency
__Type: @Boolean@__ - --
logExceptionReportingUrl
:= Defaults to a string value for an Ably error reporting Data Source Name.
__Type: @String@__ diff --git a/content/partials/types/_completion_listener.textile b/content/partials/types/_completion_listener.textile deleted file mode 100644 index 5a49a6ef42..0000000000 --- a/content/partials/types/_completion_listener.textile +++ /dev/null @@ -1,11 +0,0 @@ -A @io.ably.lib.realtime.CompletionListener@ is an interface allowing a client to be notified of the outcome of an asynchronous operation. - -```[java] - public interface CompletionListener { - // Called when the associated operation completes successfully, - public void onSuccess(); - - // Called when the associated operation completes with an error. - public void onError(ErrorInfo reason); - } -``` diff --git a/content/partials/types/_connection_event.textile b/content/partials/types/_connection_event.textile deleted file mode 100644 index 3b60d41dad..0000000000 --- a/content/partials/types/_connection_event.textile +++ /dev/null @@ -1,160 +0,0 @@ -blang[jsall]. - @ConnectionEvent@ is a String that can be emitted as an event on the @Connection@ object; either a "@Realtime Connection@ state":/docs/connect/states or an @update@ event. - - - ```[javascript] - var ConnectionEvents = [ - 'initialized', - 'connecting', - 'connected', - 'disconnected', - 'suspended', - 'closing', - 'closed', - 'failed', - 'update' - ] - ``` - -blang[java]. - @io.ably.lib.realtime.ConnectionEvent@ is an enum representing all the events that can be emitted be the @Connection@; either a "@Realtime Connection@ state":/docs/connect/states or an @update@ event. - - ```[java] - public enum ConnectionEvent { - initialized, // 0 - connecting, // 1 - connected, // 2 - disconnected, // 3 - suspended, // 4 - closing, // 5 - closed, // 6 - failed, // 7 - update // 8 - } - ``` - -blang[csharp]. - @IO.Ably.Realtime.ConnectionEvent@ is an enum representing all the events that can be emitted be the @Connection@; either a "@Realtime Connection@ state":/docs/connect/states or an @Update@ event. - - ```[csharp] - public enum ConnectionState - { - Initialized, //0 - Connecting, //1 - Connected, //2 - Disconnected, //3 - Suspended, //4 - Closing, //5 - Closed, //6 - Failed, //7 - update //8 - }; - ``` - -blang[ruby]. - @Ably::Realtime::Connection::EVENT@ is an enum-like value representing all the events that can be emitted be the @Connection@; either a "@Realtime Connection@ state":/docs/connect/states or an @:update@ event. @EVENT@ can be represented interchangeably as either symbols or constants. - - h4. Symbol states - - ```[ruby] - :initialized # => 0 - :connecting # => 1 - :connected # => 2 - :disconnected # => 3 - :suspended # => 4 - :closing # => 5 - :closed # => 6 - :failed # => 7 - :update # => 8 - ``` - - h4. Constant states - - ```[ruby] - Connection::EVENT.Initialized # => 0 - Connection::EVENT.Connecting # => 1 - Connection::EVENT.Connected # => 2 - Connection::EVENT.Disconnected # => 3 - Connection::EVENT.Suspended # => 4 - Connection::EVENT.Closing # => 5 - Connection::EVENT.Closed # => 6 - Connection::EVENT.Failed # => 7 - Connection::EVENT.Update # => 8 - ``` - - h4. Example usage - - ```[ruby] - # Example with symbols - client.connection.on(:connected) { ... } - - # Example with constants - client.connection.on(Ably::Realtime::Connection::STATE.Connected) { ... } - - # Interchangeable - Ably::Realtime::Connection::STATE.Connected == :connected # => true - ``` - -blang[objc,swift]. - @ARTRealtimeConnectionEvent@ is an enum representing all the events that can be emitted be the @Connection@; either a "@Realtime Connection@ state":/docs/connect/states or an @Update@ event. - - ```[objc] - typedef NS_ENUM(NSUInteger, ARTRealtimeConnectionEvent) { - ARTRealtimeConnectionEventInitialized, - ARTRealtimeConnectionEventConnecting, - ARTRealtimeConnectionEventConnected, - ARTRealtimeConnectionEventDisconnected, - ARTRealtimeConnectionEventSuspended, - ARTRealtimeConnectionEventClosing, - ARTRealtimeConnectionEventClosed, - ARTRealtimeConnectionEventFailed, - ARTRealtimeConnectionEventUpdate - }; - ``` - - ```[swift] - public enum ARTRealtimeConnectionEvent : UInt { - case Initialized - case Connecting - case Connected - case Disconnected - case Suspended - case Closing - case Closed - case Failed - case Update - } - ``` - -blang[go]. - @ConnectionEvent@ is a String that can be emitted as an event on the @Connection@ object; either a "@Realtime Connection@ state":/docs/connect/states or an @update@ event. - - ```[go] - const ( - StateConnInitialized = 1 - StateConnConnecting = 2 - StateConnConnected = 4 - StateConnDisconnected = 8 - StateConnSuspended = 16 - StateConnClosing = 32 - StateConnClosed = 64 - StateConnFailed = 128 - ) - ``` - -blang[flutter]. - @ably.ConnectionEvent@ is an enum representing all the events that can be emitted be the @Connection@; either a "@Realtime Connection@ state":/docs/connect/states or an @update@ event. - - ```[flutter] - enum ConnectionEvent { - initialized, - connecting, - connected, - disconnected, - suspended, - closing, - closed, - failed, - update - } - ``` diff --git a/content/partials/types/_connection_state.textile b/content/partials/types/_connection_state.textile deleted file mode 100644 index 94c127412f..0000000000 --- a/content/partials/types/_connection_state.textile +++ /dev/null @@ -1,151 +0,0 @@ -blang[jsall]. - @ConnectionState@ is a String with a value matching any of the "@Realtime Connection@ states":/docs/connect/states. - - ```[javascript] - var ConnectionStates = [ - 'initialized', - 'connecting', - 'connected', - 'disconnected', - 'suspended', - 'closing', - 'closed', - 'failed' - ] - ``` - -blang[java]. - @io.ably.lib.realtime.ConnectionState@ is an enum representing all the "@Realtime Connection@ states":/docs/connect/states. - - ```[java] - public enum ConnectionState { - initialized, // 0 - connecting, // 1 - connected, // 2 - disconnected, // 3 - suspended, // 4 - closing, // 5 - closed, // 6 - failed // 7 - } - ``` - -blang[csharp]. - @IO.Ably.Realtime.ConnectionState@ is an enum representing all the "@Realtime Connection@ states":/docs/connect/states. - - ```[csharp] - public enum ConnectionState - { - Initialized, //0 - Connecting, //1 - Connected, //2 - Disconnected, //3 - Suspended, //4 - Closing, //5 - Closed, //6 - Failed //7 - }; - ``` - -blang[ruby]. - @Ably::Realtime::Connection::STATE@ is an enum-like value representing all the "@Realtime Connection@ states":/docs/connect/states. @STATE@ can be represented interchangeably as either symbols or constants. - - h4. Symbol states - - ```[ruby] - :initialized # => 0 - :connecting # => 1 - :connected # => 2 - :disconnected # => 3 - :suspended # => 4 - :closing # => 5 - :closed # => 6 - :failed # => 7 - ``` - - h4. Constant states - - ```[ruby] - Connection::STATE.Initialized # => 0 - Connection::STATE.Connecting # => 1 - Connection::STATE.Connected # => 2 - Connection::STATE.Disconnected # => 3 - Connection::STATE.Suspended # => 4 - Connection::STATE.Closing # => 5 - Connection::STATE.Closed # => 6 - Connection::STATE.Failed # => 7 - ``` - - h4. Example usage - - ```[ruby] - # Example with symbols - client.connection.on(:connected) { ... } - - # Example with constants - client.connection.on(Ably::Realtime::Connection::STATE.Connected) { ... } - - # Interchangeable - Ably::Realtime::Connection::STATE.Connected == :connected # => true - ``` - -blang[objc,swift]. - @ARTRealtimeConnectionState@ is an enum representing all the "@Realtime Connection@ states":/docs/connect/states. - - ```[objc] - typedef NS_ENUM(NSUInteger, ARTRealtimeConnectionState) { - ARTRealtimeInitialized, - ARTRealtimeConnecting, - ARTRealtimeConnected, - ARTRealtimeDisconnected, - ARTRealtimeSuspended, - ARTRealtimeClosing, - ARTRealtimeClosed, - ARTRealtimeFailed - }; - ``` - - ```[swift] - public enum ARTRealtimeConnectionState : UInt { - case Initialized - case Connecting - case Connected - case Disconnected - case Suspended - case Closing - case Closed - case Failed - } - ``` - -blang[go]. - @ConnectionState@ is an enum representing all the "@Realtime Connection@ states":/docs/connect/states. - - ```[go] - const ( - StateConnInitialized = 1 - StateConnConnecting = 2 - StateConnConnected = 4 - StateConnDisconnected = 8 - StateConnSuspended = 16 - StateConnClosing = 32 - StateConnClosed = 64 - StateConnFailed = 128 - ) - ``` - -blang[flutter]. - @ably.ConnectionState@ is an enum representing all the "@Realtime Connection@ states":/docs/connect/states. - - ```[flutter] - enum ConnectionState { - initialized, - connecting, - connected, - disconnected, - suspended, - closing, - closed, - failed - } - ``` diff --git a/content/partials/types/_connection_state_change.textile b/content/partials/types/_connection_state_change.textile deleted file mode 100644 index 4beabdb2a0..0000000000 --- a/content/partials/types/_connection_state_change.textile +++ /dev/null @@ -1,12 +0,0 @@ -A @io.ably.lib.realtime.ConnectionStateListener.ConnectionStateChange@@Ably::Models::ConnectionStateChange@@ARTConnectionStateChange@@IO.Ably.Realtime.ConnectionStateChange@@ConnectionStateChange@ is a type encapsulating state change information emitted by the "@Connection@":/docs/api/realtime-sdk/connection object. See "@Connection#on@":/docs/api/realtime-sdk/connection#on to register a listener for one or more events. - -h4. - default: Properties - java: Members - ruby: Attributes - -- currentCurrent := the new state
__Type: "State @String@":/docs/api/realtime-sdk/types#connection-state"@Connection::STATE@":/docs/api/realtime-sdk/types#connection-state"@ConnectionState@":/docs/api/realtime-sdk/types#connection-state__ -- previousPrevious := the previous state. (for the @update@ event, this will be equal to the @current@ state)
__Type: "State @String@":/docs/api/realtime-sdk/types#connection-state"@Connection::STATE@":/docs/api/realtime-sdk/types#connection-state"@ConnectionState@":/docs/api/realtime-sdk/types#connection-state__ -- eventEvent := the event that triggered this state change
__Type: "@ConnectionEvent@Connection::EVENT@":/docs/api/realtime-sdk/types#connection-event__ -- reasonReason := an "@ErrorInfo@":#error-info containing any information relating to the transition
__Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__ -- retryInretry_inRetryIn := Duration upon which the library will retry a connection where applicable, as millisecondssecondsa @Timespan@
__Type: @Integer@@Timespan@@Long Integer@__ diff --git a/content/partials/types/_connection_state_listener.textile b/content/partials/types/_connection_state_listener.textile deleted file mode 100644 index df480e26e3..0000000000 --- a/content/partials/types/_connection_state_listener.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @io.ably.lib.realtime.ConnectionStateListener@ is an interface allowing a client to be notified of connection state change. See "@Connection#on@":/docs/api/realtime-sdk/connection#on to register a listener for one or more events. - -```[java] - public interface ConnectionStateListener { - // Called when the connection state changes - public void onConnectionStateChanged(ConnectionStateListener.ConnectionStateChange state); - } -``` diff --git a/content/partials/types/_deferrable.textile b/content/partials/types/_deferrable.textile deleted file mode 100644 index 5c7fcf15bf..0000000000 --- a/content/partials/types/_deferrable.textile +++ /dev/null @@ -1,30 +0,0 @@ -The @SafeDeferrable@ class provides an "EventMachine":https://github.com/eventmachine/eventmachine compatible "@Deferrable@":https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable. - -A @SafeDeferrable@ ensures that any exceptions in callbacks provided by developers will not break the client library and stop further execution of code. - -h4. Methods - -h6(#callback). callback - -bq(definition). callback(&block) - -Specify a block to be executed if and when the @Deferrable@ object receives a status of @:succeeded@. See the "EventMachine callback documentation":https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable#callback-instance_method - -h6(#errback). errback - -bq(definition). errback(&block) - -Specify a block to be executed if and when the @Deferrable@ object receives a status of @:failed@. See the "EventMachine errback documentation":https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable#errback-instance_method - -h6(#fail). fail - -bq(definition). fail(*args) - -Mark the @Deferrable@ as failed and trigger all callbacks. See the "EventMachine fail documentation":https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable#fail-instance_method - -h6(#succeed). succeed - -bq(definition). succeed(*args) - -Mark the @Deferrable@ as succeeded and trigger all callbacks. See the "EventMachine succeed documentation":https://www.rubydoc.info/gems/eventmachine/EventMachine/Deferrable#succeed-instance_method - diff --git a/content/partials/types/_device_details.textile b/content/partials/types/_device_details.textile deleted file mode 100644 index 203ca82761..0000000000 --- a/content/partials/types/_device_details.textile +++ /dev/null @@ -1,24 +0,0 @@ -A @DeviceDetails@ is a type encapsulating attributes of a device registered for push notifications. - -h4. - default: Properties - java: Members - ruby: Attributes - -- id := unique identifier for the device generated by the device itself
__Type: @String@__ - -- clientIdclient_id := optional trusted "client identifier":/docs/auth/identified-clients for the device
__Type: @String@__ - -- formFactorform_factor := form factor of the push device. Must be one of @phone@, @tablet@, @desktop@, @tv@, @watch@, @car@ or @embedded@@embedded@ or @other@
__Type: @String@__ - -- metadata := optional metadata object for this device. The metadata for a device may only be set by clients with @push-admin@ privileges
__Type: @Object@@Array@@Hash@__ - -- platform := platform of the push device. Must be one of @ios@ or @android@@android@ or @browser@
__Type: @String@__ - -- deviceSecret := Secret value for the device.
__Type: @String@__ - -- push.recipient := push recipient details for this device. See the "REST API push publish documentation":/docs/api/rest-api#message-extras-push for more details
__Type: @Object@@Array@@Hash@__ - -- push.state := the current state of the push device being either @Active@, @Failing@ or @Failed@@ACTIVE@, @FAILING@ or @FAILED@
__Type: @String@__ - -- push.errorReasonpush.errorpush.error_reason := when the device's state is failing or failed, this attribute contains the reason for the most recent failure
__Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__ diff --git a/content/partials/types/_error_info.textile b/content/partials/types/_error_info.textile deleted file mode 100644 index a59cf94ea0..0000000000 --- a/content/partials/types/_error_info.textile +++ /dev/null @@ -1,198 +0,0 @@ -An @ErrorInfo@ is a type encapsulating error information containing an Ably-specific error code and generic status code. - -h4. - default: Properties - java: Members - ruby: Attributes - -- codeCode := Ably error code (see "ably-common/protocol/errors.json":https://github.com/ably/ably-common/blob/main/protocol/errors.json)
__Type: @Integer@__ - -- statusCodestatus_codeStatusCode := HTTP Status Code corresponding to this error, where applicable
__Type: @Integer@__ - -- messageMessage := Additional message information, where available
__Type: @String@__ - -- causeCause := Information pertaining to what caused the error where available
__Type: @ErrorInfo@__ - -- hrefHref := Ably may additionally include a URL to get more help on this error
__Type: @String@__ - -blang[flutter]. - - requestId := Request ID with which the error can be identified
__Type: @String@__ - -h4. Error nesting - -ErrorInfo objects can contain nested errors through the @cause@ property, allowing you to trace the root cause of failures. When an operation fails due to underlying system errors, the main @ErrorInfo@ provides the high-level failure reason while the nested @cause@ contains more specific details about what went wrong. - -One example of ErrorInfo nesting is "80019: Auth server rejecting request":/docs/platform/errors/codes#80019 where the main error indicates token renewal failed, while the nested @cause@ contains the specific HTTP error from the auth server. - -blang[javascript,nodejs,ruby,java,swift,objc,csharp,flutter,python,go]. - The following example demonstrates how to handle nested errors: - -blang[javascript]. - ```[javascript] - function handleError(error) { - console.log(`Main error: ${error.code} - ${error.message}`); - - // Check for nested error - if (error.cause) { - console.log(`Root cause: ${error.cause.code} - ${error.cause.message}`); - - // Handle further nesting if needed - if (error.cause.cause) { - console.log(`Deeper cause: ${error.cause.cause.code} - ${error.cause.cause.message}`); - } - } - } - ``` - -blang[nodejs]. - ```[javascript] - function handleError(error) { - console.log(`Main error: ${error.code} - ${error.message}`); - - // Check for nested error - if (error.cause) { - console.log(`Root cause: ${error.cause.code} - ${error.cause.message}`); - - // Handle further nesting if needed - if (error.cause.cause) { - console.log(`Deeper cause: ${error.cause.cause.code} - ${error.cause.cause.message}`); - } - } - } - ``` - -blang[swift]. - ```[swift] - func handleError(_ error: ARTErrorInfo) { - print("Main error: \(error.code) - \(error.message)") - - if let cause = error.cause { - print("Root cause: \(cause.code) - \(cause.message)") - - if let deeperCause = cause.cause { - print("Deeper cause: \(deeperCause.code) - \(deeperCause.message)") - } - } - } - ``` - -blang[objc]. - ```[objc] - - (void)handleError:(ARTErrorInfo *)error { - NSLog(@"Main error: %ld - %@", (long)error.code, error.message); - - if (error.cause) { - NSLog(@"Root cause: %ld - %@", (long)error.cause.code, error.cause.message); - - if (error.cause.cause) { - NSLog(@"Deeper cause: %ld - %@", (long)error.cause.cause.code, error.cause.cause.message); - } - } - } - ``` - -blang[flutter]. - ```[flutter] - void handleError(ably.ErrorInfo error) { - print('Main error: ${error.code} - ${error.message}'); - - if (error.cause != null) { - print('Root cause: ${error.cause!.code} - ${error.cause!.message}'); - - if (error.cause!.cause != null) { - print('Deeper cause: ${error.cause!.cause!.code} - ${error.cause!.cause!.message}'); - } - } - } - ``` - -blang[java]. - ```[java] - public void handleError(ErrorInfo error) { - System.out.println("Main error: " + error.code + " - " + error.message); - - if (error.cause != null) { - System.out.println("Root cause: " + error.cause.code + " - " + error.cause.message); - - if (error.cause.cause != null) { - System.out.println("Deeper cause: " + error.cause.cause.code + " - " + error.cause.cause.message); - } - } - } - ``` - -blang[csharp]. - ```[csharp] - void HandleError(ErrorInfo error) - { - Console.WriteLine($"Main error: {error.Code} - {error.Message}"); - - if (error.Cause != null) - { - Console.WriteLine($"Root cause: {error.Cause.Code} - {error.Cause.Message}"); - - if (error.Cause.Cause != null) - { - Console.WriteLine($"Deeper cause: {error.Cause.Cause.Code} - {error.Cause.Cause.Message}"); - } - } - } - ``` - -blang[ruby]. - ```[ruby] - def handle_error(error) - puts "Main error: #{error.code} - #{error.message}" - - if error.cause - puts "Root cause: #{error.cause.code} - #{error.cause.message}" - - if error.cause.cause - puts "Deeper cause: #{error.cause.cause.code} - #{error.cause.cause.message}" - end - end - end - ``` - - -blang[python]. - ```[python] - def handle_error(error): - print(f"Main error: {error.code} - {error.message}") - - if error.cause: - print(f"Root cause: {error.cause.code} - {error.cause.message}") - - if error.cause.cause: - print(f"Deeper cause: {error.cause.cause.code} - {error.cause.cause.message}") - ``` - -blang[php]. - ```[php] - function handleError($error) { - echo "Main error: " . $error->code . " - " . $error->message . "\n"; - - if ($error->cause) { - echo "Root cause: " . $error->cause->code . " - " . $error->cause->message . "\n"; - - if ($error->cause->cause) { - echo "Deeper cause: " . $error->cause->cause->code . " - " . $error->cause->cause->message . "\n"; - } - } - } - ``` - -blang[go]. - ```[go] - func handleError(err *ErrorInfo) { - fmt.Printf("Main error: %d - %s\n", err.Code, err.Message) - - if err.Cause != nil { - fmt.Printf("Root cause: %d - %s\n", err.Cause.Code, err.Cause.Message) - - if err.Cause.Cause != nil { - fmt.Printf("Deeper cause: %d - %s\n", err.Cause.Cause.Code, err.Cause.Cause.Message) - } - } - } - ``` diff --git a/content/partials/types/_history_request_params.textile b/content/partials/types/_history_request_params.textile deleted file mode 100644 index 735dbab715..0000000000 --- a/content/partials/types/_history_request_params.textile +++ /dev/null @@ -1,9 +0,0 @@ -@HistoryRequestParams@ is a type that encapsulates the parameters for a history queries. For example usage see "@Channel#history@@Channel#History@":/docs/api/realtime-sdk/history#channel-history. - -h4. Members - -- Start := _null_ The start of the queried interval
__Type: @DateTimeOffset@__ -- End := _null_ The end of the queried interval
__Type: @DateTimeOffset@__ -- Limit := _null_ By default it is null. Limits the number of items returned by history or stats
__Type: @Integer@__ -- Direction := _Backwards_ Enum which is either @Forwards@ or @Backwards@
__Type: @Direction@ enum__ -- ExtraParameters := Optionally any extra query parameters that may be passed to the query. This is mainly used internally by the library to manage paging.
__Type: @Dictionary@__ diff --git a/content/partials/types/_http_paginated_response.textile b/content/partials/types/_http_paginated_response.textile deleted file mode 100644 index 44179667ad..0000000000 --- a/content/partials/types/_http_paginated_response.textile +++ /dev/null @@ -1,110 +0,0 @@ -An @HttpPaginatedResponse@ is a superset of "@PaginatedResult@":/docs/api/rest-sdk/types#paginated-result, which is a type that represents a page of results plus metadata indicating the relative queries available to it. @HttpPaginatedResponse@ additionally carries information about the response to an HTTP request. It is used when "making custom HTTP requests":/docs/api/rest-sdk#request. - -h4. - default: Properties - java: Members - ruby: Attributes - python: Attributes - --
items
:= contains a page of results; for example, an array of "@Message@":#message or "@PresenceMessage@":#presence-message objects for a channel history request
__Type: @Array<>@__ --
Items
:= contains a page of results; for example, an array of "@Message@":#message or "@PresenceMessage@":#presence-message objects for a channel history request
__Type: @Array<>@__ --
items
:= contains a page of results; for example, an array of "@Message@":#message or "@PresenceMessage@":#presence-message objects for a channel history request
__Type: @List<>@__ -- statusCodestatus_codeStatusCode := the HTTP status code of the response
__Type: @Number@__ -- successSuccess := whether the HTTP status code indicates success. This is equivalent to @200 <= statusCode < 300@@200 <= status_code < 300@@200 <= StatusCode < 300@
__Type: @Boolean@__ -- headersHeaders := the headers of the response
__Type: @Object@__ -- errorCodeerror_codeErrorCode := the error code if the @X-Ably-Errorcode@ HTTP header is sent in the response
__Type: @Int@@Number@__ -- errorMessageerror_messageErrorMessage := the error message if the @X-Ably-Errormessage@ HTTP header is sent in the response
__Type: @String@__ - - -h4. Methods - -h6. - default: first - csharp: First - -bq(definition). - default: first(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response resultPage)) - jsall: first(): Promise<"HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response> - ruby: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response first - php: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response first() - python: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response first() - csharp: Task> FirstAsync() - java: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response first() - swift,objc: first(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void) - go: First() ("HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response, error) - -blang[default]. - Returns a new @HttpPaginatedResponse@ for the first page of results. When using the Realtime library, the @first@ method returns a "Deferrable":/docs/api/realtime-sdk/types#deferrable and yields an "@HttpPaginatedResponse@":/docs/api/realtime-sdk/types#http-paginated-response.The method is asynchronous and returns a Task which needs to be awaited to get the @HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response. - -blang[jsall]. - Returns a promise. On success, the promise is fulfilled with a new @HttpPaginatedResponse@ for the first page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -h6. - default: hasNext - csharp,go: HasNext - ruby: has_next? - python: has_next - -bq(definition). - default: Boolean hasNext() - ruby: Boolean has_next? - php: Boolean hasNext() - python: Boolean has_next() - csharp: Boolean HasNext() - java: Boolean hasNext() - swift,objc: Boolean hasNext() - go: HasNext() (bool) - -Returns @true@ if there are more pages available by calling @next@@Next@ and returns @false@ if this page is the last page available. - -h6. - default: isLast - csharp,go: IsLast - ruby: last? - python: is_last - -bq(definition). - default: Boolean isLast() - ruby: Boolean last? - php: Boolean isLast() - python: Boolean is_last() - csharp: Boolean IsLast() - java: Boolean isLast() - swift,objc: Boolean isLast() - go: IsLast() (bool) - -Returns @true@ if this page is the last page and returns @false@ if there are more pages available by calling @next@@Next@ available. - -h6. - default: next - csharp,go: Next - -bq(definition). - default: next(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response resultPage)) - jsall: next(): Promise<"HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response> - ruby: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response next - php: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response next() - python: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response next() - csharp: Task<"HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response > NextAsync() - java: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response next() - swift,objc: next(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void) - go: Next() ("HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response, error) - -blang[default]. - Returns a new @HttpPaginatedResponse@ loaded with the next page of results. If there are no further pages, then @null@a blank HttpPaginatedResponse will be returned@Null@@None@@nil@ is returned. The method is asynchronous and return a Task which needs to be awaited to get the @HttpPaginatedResponse@When using the Realtime library, the @first@ method returns a "Deferrable":/docs/api/realtime-sdk/types#deferrable and yields an "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response. - -blang[jsall]. - Returns a promise. On success, the promise is fulfilled with a new @HttpPaginatedResponse@ loaded with the next page of results. If there are no further pages, then @null@ is returned. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[jsall]. - h6(#current). - default: current - - bq(definition). - default: current(): Promise<"HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response> - - Returns a promise. On success, the promise is fulfilled with a new @HttpPaginatedResponse@ loaded with the current page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -h4. Example - -The @HttpPaginatedResponse@ interface is a superset of @PaginatedResult@, see the "@PaginatedResult@ example":/docs/api/rest-sdk/types/#paginated-result-example diff --git a/content/partials/types/_last_connection_details.textile b/content/partials/types/_last_connection_details.textile deleted file mode 100644 index 780553f722..0000000000 --- a/content/partials/types/_last_connection_details.textile +++ /dev/null @@ -1,14 +0,0 @@ -A @LastConnectionDetails@ object provides details on the last connection in a browser environment persisted when the @window beforeunload@ fired. This object is provided to the callback specified in the @recover@ attribute of "@ClientOptions@":/docs/api/realtime-sdk/types#client-options. The callback in turn instructs the client library whether the connection should be recovered or not. See "connection state recovery":/docs/connect/states for more information. - -Please note that as "@sessionStorage@":https://www.w3.org/TR/webstorage/ is used to persist the @LastConnectionDetails@ between page reloads, it is only available for pages in the same origin and top-level browsing context. - -h4. - default: Properties - -- recoveryKey := An opaque string obtained from the "recoveryKey":/docs/api/realtime-sdk/connection#recovery-key attribute of the "Connection object":/docs/api/realtime-sdk/connection before the page was unloaded. This property is used by the library to recover the connection
__Type: @String@__ - -- disconnectedAt := the time at which the previous library was abruptly disconnected before the page was unloaded. This is represented as milliseconds since epoch
__Type: @Integer@__ - -- location := a clone of "@location@":https://www.w3.org/TR/html5/browsers.html#the-location-interface object of the previous page's @document@ object before the page was unloaded. A common use case for this attribute is to ensure that the previous page URL is the same as the current URL before allowing the connection to be recovered. For example, you may want the connection to be recovered only for page reloads, but not when a user navigates to a different page
__Type: @String@__ - -- clientId := the "@clientId@":/docs/api/realtime-sdk/authentication/#client-id of the "client's Auth object":/docs/api/realtime-sdk/authentication before the page was unloaded. A common use case for this attribute is to ensure that the current logged in user's @clientId@ matches the previous connection's @clientId@ before allowing the connection to be recovered. Ably prohibits changing a @clientId@ for an existing connection, so any mismatch in @clientId@ during a recover will result in the connection moving to the failed state
__Type: @String@__ diff --git a/content/partials/types/_local_device.textile b/content/partials/types/_local_device.textile deleted file mode 100644 index 19b8663953..0000000000 --- a/content/partials/types/_local_device.textile +++ /dev/null @@ -1,30 +0,0 @@ -
-An extension of "@DeviceDetails@":#device-details. In addition to the propertiesmembersattributes of "@DeviceDetails@":#device-details, it includes the following: -
-
Contains the device identity token and secret of a device.
- -h4. - default: Properties - java: Members - ruby: Attributes - --
id
:= a unique ID generated by the device
__Type: @String@__ --
deviceSecret
:= a unique device secret generated by the Ably SDK
__Type: @String@__ - -- deviceIdentityToken := a unique identity token for the device
__Type: @String@__ - -
-h4. Methods - -h6. - jsall: listSubscriptions - -bq(definition). - jsall: listSubscriptions(): Promise<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"PushChannelSubscription":/docs/api/realtime-sdk/types#push-channel-subscription>> - -Retrieves push subscriptions active for the local device. - -h4. Returns - -Returns a promise. On success, the promise is fulfilled with a "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result object containing an array of "PushChannelSubscription":/docs/api/realtime-sdk/types#push-channel-subscription objects for each push channel subscription active for the local device. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object that details the reason why it was rejected. -
diff --git a/content/partials/types/_location_pushes.textile b/content/partials/types/_location_pushes.textile deleted file mode 100644 index 4739d0a717..0000000000 --- a/content/partials/types/_location_pushes.textile +++ /dev/null @@ -1,8 +0,0 @@ -Starting with iOS 15, Apple supports a power-efficient way to request location through the location push service extension. - -The following table explains how to receive location push notifications: - -|_. Action |_. Details | -| Request location token | Call @CLLocationManager.startMonitoringLocationPushes(completion:)@ within the @ARTPushRegistererDelegate.didActivateAblyPush(:)@ delegate method. This delegate method is the callback for @ARTRealtime.push.activate()@. | -| Register with Ably | Call @ARTPush.didRegisterForLocationNotifications(withDeviceToken:realtime:)@ when you receive the location push token. Note the "Location" in the method name to distinguish it from regular push tokens. | -| Handle result | Use the @ARTPushRegistererDelegate.didUpdateAblyPush:@ callback, which indicates whether the token was successfully saved. | diff --git a/content/partials/types/_message.textile b/content/partials/types/_message.textile deleted file mode 100644 index 00f65e50bb..0000000000 --- a/content/partials/types/_message.textile +++ /dev/null @@ -1,131 +0,0 @@ -A @Message@ represents an individual message that is sent to or received from Ably. - -h6(#name). - default: name - csharp: Name - -The event name, if provided.
__Type: @String@__ - -h6(#data). - default: data - csharp: Data - -The message payload, if provided.
__Type: @String@, @StringBuffer@, @JSON Object@@String@, @ByteArray@, @JSONObject@, @JSONArray@@String@, @byte[]@, @plain C# object that can be serialized to JSON@@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@@String@, @Bytearray@, @Dict@, @List@@String@, @Binary String@, @Associative Array@, @Array@@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@@String@, @NSData@, @Dictionary@, @Array@@String@, @Map@, @List@__ - -h6(#extras). - default: extras - csharp: Extras - -Metadata and/or ancillary payloads, if provided. Valid payloads include "@push@":/docs/push/publish#payload, "@headers@" (a map of strings to strings for arbitrary customer-supplied metadata), "@ephemeral@":/docs/pub-sub/advanced#ephemeral, and "@privileged@":/docs/platform/integrations/webhooks#skipping objects.
__Type: @JSONObject@, @JSONArray@plain C# object that can be converted to JSON@JSON Object@@Hash@, @Array@@Dict@, @List@@Dictionary@, @Array@@NSDictionary *@, @NSArray *@@Associative Array@, @Array@__ - -h6(#id). - default: id - csharp: Id - -A Unique ID assigned by Ably to this message.
__Type: @String@__ - -h6(#client-id). - default: clientId - csharp: ClientId - ruby: client_id - python: client_id - -The client ID of the publisher of this message.
__Type: @String@__ - -h6(#connection-id). - default: connectionId - csharp: ConnectionId - ruby: connection_id - python: connection_id - -The connection ID of the publisher of this message.
__Type: @String@__ - -h6(#connection-key). - default: connectionKey - csharp,go: ConnectionKey - ruby,python: connection_key - -A connection key, which can optionally be included for a REST publish as part of the "publishing on behalf of a realtime client functionality":/docs/pub-sub/advanced#publish-on-behalf.
__Type: @String@__ - -h6(#timestamp). - default: timestamp - csharp: Timestamp - -Timestamp when the message was first received by the Ably, as milliseconds since the epocha @Time@ object
.__Type: @Integer@@Long Integer@@DateTimeOffset@@Time@@NSDate@__ - -h6(#encoding). - default: encoding - csharp: Encoding - -This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the @data@ payload.
__Type: @String@__ - -blang[jsall]. - - h6(#action). - default: action - - The action type of the message, one of the "@MessageAction@":#message-action enum values.
__Type: @int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }@__ - - h6(#serial). - default: serial - - A server-assigned identifier that will be the same in all future updates of this message. It can be used to add "annotations":/docs/messages/annotations to a message or to "update or delete":/docs/messages/updates-deletes it. Serial will only be set if you enable annotations, updates, and deletes in "channel rules":/docs/channels#rules .
__Type: @String@__ - - h6(#annotations). - default: annotations - - An object containing information about annotations that have been made to the object.
__Type: "@MessageAnnotations@":/docs/api/realtime-sdk/types#message-annotations__ - - h6(#version). - default: version - - An object containing version metadata for messages that have been updated or deleted. See "updating and deleting messages":/docs/messages/updates-deletes for more information.
__Type: "@MessageVersion@":#message-version__ - -h3(constructors). - default: Message constructors - -h6(#message-from-encoded). - default: Message.fromEncoded - -bq(definition). - default: Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message - -A static factory method to create a "@Message@":/docs/api/realtime-sdk/types#message from a deserialized @Message@-like object encoded using Ably's wire protocol. - -h4. Parameters - -- encodedMsg := a @Message@-like deserialized object.
__Type: @Object@__ -- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.
__Type: @Object@__ - -h4. Returns - -A "@Message@":/docs/api/realtime-sdk/types#message object - -h6(#message-from-encoded-array). - default: Message.fromEncodedArray - -bq(definition). - default: Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[] - -A static factory method to create an array of "@Messages@":/docs/api/realtime-sdk/types#message from an array of deserialized @Message@-like object encoded using Ably's wire protocol. - -h4. Parameters - -- encodedMsgs := an array of @Message@-like deserialized objects.
__Type: @Array@__ -- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.
__Type: @Object@__ - -h4. Returns - -An @Array@ of "@Message@":/docs/api/realtime-sdk/types#message objects - -h3(#message-version). - default: MessageVersion - -h4. Properties - -|_. Property |_. Description |_. Type | -| serial | An Ably-generated ID that uniquely identifies this version of the message. Can be compared lexicographically to determine version ordering. For an original message with an action of @message.create@, this will be equal to the top-level @serial@. | @String@ | -| timestamp | The time this version was created (when the update or delete operation was performed). For an original message, this will be equal to the top-level @timestamp@. | @Integer@@Long Integer@@DateTimeOffset@@Time@@NSDate@ | -| clientId | The client identifier of the user who performed the update or delete operation. Only present for @message.update@ and @message.delete@ actions. | @String@ (optional) | -| description | Optional description provided when the update or delete was performed. Only present for @message.update@ and @message.delete@ actions. | @String@ (optional) | -| metadata | Optional metadata provided when the update or delete was performed. Only present for @message.update@ and @message.delete@ actions. | @Object@ (optional) | diff --git a/content/partials/types/_message_action.textile b/content/partials/types/_message_action.textile deleted file mode 100644 index ef6d69b2ae..0000000000 --- a/content/partials/types/_message_action.textile +++ /dev/null @@ -1,61 +0,0 @@ -blang[default]. - @MessageAction@ is an enum representing the action type of the message. - - ``` - enum MessageAction { - MESSAGE_CREATE, // 0 - MESSAGE_UPDATE, // 1 - MESSAGE_DELETE, // 2 - META, // 3 - MESSAGE_SUMMARY // 4 - } - ``` - -blang[jsall]. - @Message@ @action@ is a String representing the action type of the message. - - ```[javascript] - var MessageActions = [ - 'message.create', - 'message.update', - 'message.delete', - 'meta', - 'message.summary' - ] - ``` - -blang[java]. - @io.ably.lib.types.Message.Action@ is an enum representing the action type of the message. - - ```[java] - public enum Action { - MESSAGE_CREATE, // 0 - MESSAGE_UPDATE, // 1 - MESSAGE_DELETE, // 2 - META, // 3 - MESSAGE_SUMMARY // 4 - } - ``` - -blang[objc,swift]. - @ARTMessageAction@ is an enum representing the action type of the message. - - ```[objc] - typedef NS_ENUM(NSUInteger, ARTMessageAction) { - ARTMessageActionCreate, - ARTMessageActionUpdate, - ARTMessageActionDelete, - ARTMessageActionMeta, - ARTMessageActionMessageSummary - }; - ``` - - ```[swift] - enum ARTMessageAction : UInt { - case Create - case Update - case Delete - case Meta - case Summary - } - ``` diff --git a/content/partials/types/_message_annotations.textile b/content/partials/types/_message_annotations.textile deleted file mode 100644 index 69fad98670..0000000000 --- a/content/partials/types/_message_annotations.textile +++ /dev/null @@ -1,7 +0,0 @@ -h4. - default: Properties - java: Members - ruby: Attributes - python: Attributes - -- summary := An object whose keys are annotation types, and the values are aggregated summaries for that annotation type
__Type: @Record@__ diff --git a/content/partials/types/_message_listener.textile b/content/partials/types/_message_listener.textile deleted file mode 100644 index f328f11a42..0000000000 --- a/content/partials/types/_message_listener.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @io.ably.lib.realtime.Channel.MessageListener@ is an interface allowing a client to be notified when messages are received on a channel using a "channel subscription":/docs/pub-sub#subscribe. - -```[java] - public interface MessageListener { - // Called when one or more messages are received - public void onMessage(Message message); - } -``` diff --git a/content/partials/types/_paginated_result.textile b/content/partials/types/_paginated_result.textile deleted file mode 100644 index 0d496424af..0000000000 --- a/content/partials/types/_paginated_result.textile +++ /dev/null @@ -1,212 +0,0 @@ -A @PaginatedResult@ is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a "Ably REST API paginated query":/docs/api/rest-api/#pagination is accompanied by metadata that indicates the relative queries available to the @PaginatedResult@ object. - -h4. - default: Properties - java: Members - ruby: Attributes - --
items
:= contains the current page of results (for example an Array of "@Message@":#message or "@PresenceMessage@":#presence-message objects for a channel history request)
__Type: @Array @__ --
Items
:= contains the current page of results (for example an Array of "@Message@":#message or "@PresenceMessage@":#presence-message objects for a channel history request)
__Type: @List @__ --
Items
:= contains the current page of results (for example an Array of "@Message@":#message or "@PresenceMessage@":#presence-message objects for a channel history request)
__Type: @Array @__ --
items
:= contains the current page of results (for example an Array of "@Message@":#message or "@PresenceMessage@":#presence-message objects for a channel history request)
__Type: @List @__ - -h4. Methods - -h6. - default: first - csharp: First - -bq(definition). - default: first(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result resultPage)) - jsall: first(): Promise<"PaginatedResult":#paginated-result> - ruby: "PaginatedResult":#paginated-result first - php: "PaginatedResult":#paginated-result first() - python: "PaginatedResult":#paginated-result first() - csharp: Task> FirstAsync() - java: "PaginatedResult":#paginated-result first() - swift,objc: first(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void) - go: First() ("PaginatedResult":#paginated-result, error) - - -blang[default]. - Returns a new @PaginatedResult@ for the first page of results. When using the Realtime library, the @first@ method returns a "Deferrable":/docs/api/realtime-sdk/types#deferrable and yields a "PaginatedResult":#paginated-result.The method is asynchronous and returns a Task which needs to be awaited to get the "PaginatedResult":#paginated-result. - -blang[jsall]. - Returns a promise. On success, the promise is fulfilled with a new @PaginatedResult@ for the first page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -h6. - default: hasNext - csharp: HasNext - ruby: has_next? - python: has_next - -bq(definition). - default: Boolean hasNext() - ruby: Boolean has_next? - php: Boolean hasNext() - python: Boolean has_next() - csharp: Boolean HasNext() - java: Boolean hasNext() - swift,objc: Boolean hasNext() - go: HasNext() (bool) - -Returns @true@ if there are more pages available by calling @next@@Next@ and returns @false@ if this page is the last page available. - -h6. - default: isLast - csharp: IsLast - ruby: last? - python: is_last - -bq(definition). - default: Boolean isLast() - ruby: Boolean last? - php: Boolean isLast() - python: Boolean is_last() - csharp: Boolean IsLast() - java: Boolean isLast() - swift,objc: Boolean isLast() - go: IsLast() (bool) - -Returns @true@ if this page is the last page and returns @false@ if there are more pages available by calling @next@@Next@ available. - -h6. - default: next - csharp: Next - -bq(definition). - default: next(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result resultPage)) - jsall: next(): Promise<"PaginatedResult":#paginated-result | null> - ruby: "PaginatedResult":#paginated-result next - php: "PaginatedResult":#paginated-result next() - python: "PaginatedResult":#paginated-result next() - csharp: Task<"PaginatedResult":#paginated-result> NextAsync() - java: "PaginatedResult":#paginated-result next() - swift,objc: next(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void) - go: Next() ("PaginatedResult":#paginated-result, error) - -blang[default]. - Returns a new @PaginatedResult@ loaded with the next page of results. If there are no further pages, then @null@a blank PaginatedResult will be returned@Null@@None@@nil@ is returned. The method is asynchronous and return a Task which needs to be awaited to get the @PaginatedResult@When using the Realtime library, the @first@ method returns a "Deferrable":/docs/api/realtime-sdk/types#deferrable and yields a "PaginatedResult":#paginated-result. - -blang[jsall]. - Returns a promise. On success, the promise is fulfilled with a new @PaginatedResult@ loaded with the next page of results. If there are no further pages, then @null@ is returned. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[jsall]. - h6(#current). - default: current - - bq(definition). - default: current(): Promise<"PaginatedResult":#paginated-result> - - Returns a promise. On success, the promise is fulfilled with a new @PaginatedResult@ loaded with the current page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -h4(#paginated-result-example). Example - -```[jsall] -const paginatedResult = await channel.history(); -console.log('Page 0 item 0:' + paginatedResult.items[0].data); -const nextPage = await paginatedResult.next(); -console.log('Page 1 item 1: ' + nextPage.items[1].data); -console.log('Last page?: ' + nextPage.isLast()); -``` - -```[java] -PaginatedResult firstPage = channel.history(); -System.out.println("Page 0 item 0:" + firstPage.items[0].data); -if (firstPage.hasNext) { - PaginatedResult nextPage = firstPage.next(); - System.out.println("Page 1 item 1:" + nextPage.items[1].data); - System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext())); -}; -``` - -```[csharp] -PaginatedResult firstPage = await channel.HistoryAsync(null); -Message firstMessage = firstPage.Items[0]; -Console.WriteLine("Page 0 item 0: " + firstMessage.data); -if (firstPage.HasNext) -{ - var nextPage = await firstPage.NextAsync(); - Console.WriteLine("Page 1 item 1:" + nextPage.Items[1].data); - Console.WriteLine("More pages?: " + nextPage.HasNext()); -} -``` - -```[ruby] -# When using the REST sync library -first_page = channel.history -puts "Page 0 item 0: #{first_page.items[0].data}" -if first_page.has_next? - next_page = first_page.next - puts "Page 1 item 1: #{next_page.items[1].data}" - puts "Last page?: #{next_page.is_last?}" -end - -# When using the Realtime EventMachine library -channel.history do |first_page| - puts "Page 0 item 0: #{first_page.items[0].data}" - if first_page.has_next? - first_page.next do |next_page| - puts "Page 1 item 1: #{next_page.items[1].data}" - puts "Last page?: #{next_page.is_last?}" - end - end -end -``` - -```[python] -result_page = channel.history() -print 'Page 0 item 0: ' + str(result_page.items[0].data) -if result_page.has_next(): - next_page = result_page.next() - print 'Page 1 item 1: ' + str(next_page.items[1].data) - print 'Last page?: ' + str(next_page.is_last()) -``` - -```[php] -$firstPage = $channel.history(); -echo("Page 0 item 0: " . $firstPage->items[0]->data); -if ($firstPage->hasNext()) { - $nextPage = $firstPage->next(); - echo("Page 1 item 1: " . $nextPage->items[1]->data); - echo("Last page?: " . $nextPage->isLast()); -} -``` - -```[objc] -[channel history:^(ARTPaginatedResult *paginatedResult, ARTErrorInfo *error) { - NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data); - [paginatedResult next:^(ARTPaginatedResult *nextPage, ARTErrorInfo *error) { - NSLog(@"Page 1 item 1: %@", nextPage.items[1].data); - NSLog(@"Last page?: %d", nextPage.isLast()); - }]; -}]; -``` - -```[swift] -channel.history { paginatedResult, error in - guard let paginatedResult = paginatedResult else { - print("No results available") - return - } - print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)") - paginatedResult.next { nextPage, error in - guard let nextPage = nextPage else { - print("No next page available") - return - } - print("Page 1 item 1: \((nextPage.items[1] as! ARTMessage).data)") - print("Last page? \(nextPage.isLast())") - } -} -``` - -```[go] - page0, err := channel.History(nil) - fmt.Println("Page. 0 item 0: %s\n", page0.Messages[0].Data) - page1, err := page0.Next() - fmt.Println("Page. 1 item 1: %s\n", page1.Messages[1].Data) - fmt.Println("Last page? %s\n", page1.IsLast()) -``` - - diff --git a/content/partials/types/_param.textile b/content/partials/types/_param.textile deleted file mode 100644 index dc93597542..0000000000 --- a/content/partials/types/_param.textile +++ /dev/null @@ -1,10 +0,0 @@ -@Param@ is a type encapsulating a key/value pair. This type is used frequently in method parameters allowing key/value pairs to be used more flexible, see "@Channel#history@":/docs/api/realtime-sdk/history#channel-history for an example. - -Please note that @key@ and @value@ attributes are always strings. If an @Integer@ or other value type is expected, then you must coerce that type into a @String@. - -h4. - java: Members - -- key := The key value
__Type: @String@__ -- value := The value associated with the @key@
__Type: @String@__ - diff --git a/content/partials/types/_presence_action.textile b/content/partials/types/_presence_action.textile deleted file mode 100644 index d9e095bd0f..0000000000 --- a/content/partials/types/_presence_action.textile +++ /dev/null @@ -1,146 +0,0 @@ -blang[jsall]. - @Presence@ @action@ is a String with a value matching any of the "@Realtime Presence@ states & events":/docs/presence-occupancy/presence#trigger-events. - - ```[javascript] - var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' - ] - ``` - -blang[java]. - @io.ably.lib.types.PresenceMessage.Action@ is an enum representing all the "@Realtime Presence@ states & events":/docs/presence-occupancy/presence#trigger-events. - - ```[java] - public enum Action { - ABSENT, // 0 (reserved for internal use) - PRESENT, // 1 - ENTER, // 2 - LEAVE, // 3 - UPDATE // 4 - } - ``` - -blang[csharp]. - @IO.Ably.PresenceAction@ is an enum representing all the "@Realtime Presence@ states & events":/docs/presence-occupancy/presence#trigger-events. - - ```[csharp] - public enum Action { - Absent, // 0 (reserved for internal use) - Present, // 1 - Enter, // 2 - Leave, // 3 - Update // 4 - } - ``` - -blang[python]. - @PresenceAction@ is an enum-like class representing all the "@Realtime Presence@ states & events":/docs/presence-occupancy/presence#trigger-events. - - ```[python] - class PresenceAction(object): - ABSENT = 0 # (reserved for internal use) - PRESENT = 1 - ENTER = 2 - LEAVE = 3 - UPDATE = 4 - ``` - -blang[php]. - @PresenceMessage Action@ is one of the class constants representing all the "@Realtime Presence@ states & events":/docs/presence-occupancy/presence#trigger-events. - - ```[php] - namespace Ably\Models; - class PresenceMessages { - const ABSENT = 0; /* (reserved for internal use) */ - const PRESENT = 1; - const ENTER = 2; - const LEAVE = 3; - const UPDATE = 4; - } - ``` - - h4. Example usage - - ```[php] - if ($presenceMessage->action == Ably\Models\PresenceMesage::ENTER) { - /* do something */ - } - ``` - -blang[ruby]. - @Ably::Models::PresenceMessage::ACTION@ is an enum-like value representing all the "@Realtime Presence@ states & events":/docs/presence-occupancy/presence#trigger-events. @ACTION@ can be represented interchangeably as either symbols or constants. - - h4. Symbol states - - ```[ruby] - :absent # => 0 (reserved for internal use) - :present # => 1 - :enter # => 2 - :leave # => 3 - :update # => 4 - ``` - - h4. Constant states - - ```[ruby] - PresenceMessage::ACTION.Absent # => 0 (internal use) - PresenceMessage::ACTION.Present # => 1 - PresenceMessage::ACTION.Enter # => 2 - PresenceMessage::ACTION.Leave # => 3 - PresenceMessage::ACTION.Update # => 4 - ``` - - h4. Example usage - - ```[ruby] - # Example with symbols - presence.on(:attached) { ... } - - # Example with constants - presence.on(Ably::Models::PresenceMessage::ACTION.Enter) { ... } - - # Interchangeable - Ably::Models::PresenceMessage::ACTION.Enter == :enter # => true - ``` - -blang[objc,swift]. - @ARTPresenceAction@ is an enum representing all the "@Realtime Presence@ states & events":/docs/presence-occupancy/presence#trigger-events. - - ```[objc] - typedef NS_ENUM(NSUInteger, ARTPresenceAction) { - ARTPresenceAbsent, // reserved for internal use - ARTPresencePresent, - ARTPresenceEnter, - ARTPresenceLeave, - ARTPresenceUpdate - }; - ``` - - ```[swift] - enum ARTPresenceAction : UInt { - case Absent // reserved for internal use - case Present - case Enter - case Leave - case Update - } - ``` - -blang[go]. - @Presence@ @action@ is a String with a value matching any of the "@Realtime Presence@ states & events":/docs/presence-occupancy/presence#trigger-events. - - ```[go] - const ( - PresenceAbsent = 0 - PresencePresent = 1 - PresenceEnter = 2 - PresenceLeave = 3 - PresenceUpdate = 4 - ) - ``` - -
\ No newline at end of file diff --git a/content/partials/types/_presence_listener.textile b/content/partials/types/_presence_listener.textile deleted file mode 100644 index c4bb846fed..0000000000 --- a/content/partials/types/_presence_listener.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @io.ably.lib.realtime.Presence.PresenceListener@ is an interface allowing a client to be notified when presence message events are received on a presence channel using a "presence subscription":/docs/presence-occupancy/presence. - -```[java] - public interface PresenceListener { - // Called when one or more presence messages are received - public void onPresenceMessage(PresenceMessage message); - } -``` diff --git a/content/partials/types/_presence_message.textile b/content/partials/types/_presence_message.textile deleted file mode 100644 index 8139a7882d..0000000000 --- a/content/partials/types/_presence_message.textile +++ /dev/null @@ -1,66 +0,0 @@ -A @PresenceMessage@ represents an individual presence update that is sent to or received from Ably. - -h4. - default: Properties - java: Members - ruby: Attributes - --
action
:= the event signified by a PresenceMessage. See "@PresenceMessage.action@":/docs/api/realtime-sdk/types#presence-action
__Type: @enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }@__ --
Action
:= the event signified by a PresenceMessage. See "@PresenceMessage.action@":/docs/api/realtime-sdk/types#presence-action
__Type: @enum { Absent, Present, Enter, Leave, Update }@__ --
action
:= the event signified by a PresenceMessage. See "@Presence action@":/docs/api/realtime-sdk/types#presence-action
__Type: @int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }@__ --
action
:= the event signified by a PresenceMessage. See "@PresenceAction@":/docs/api/realtime-sdk/types#presence-action
__Type: @int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }@__ --
action
:= the event signified by a PresenceMessage. See "@PresenceMessage::ACTION@":/docs/api/realtime-sdk/types#presence-action
__Type: @enum { :absent, :present, :enter, :leave, :update }@__ --
action
:= the event signified by a PresenceMessage. See "@PresenceMessage::ACTION@":/docs/api/realtime-sdk/types#presence-action
__Type: @const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE@__ --
action
:= the event signified by a PresenceMessage. See "@PresenceMessage.action@":/docs/api/realtime-sdk/types#presence-action
__Type: @ARTPresenceAction@__ --
Action
:= the event signified by a PresenceMessage. See "@PresenceMessage::action@":/docs/api/realtime-sdk/types#presence-action
__Type: @const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate@__ - -- dataData := The presence update payload, if provided
__@String@, @ByteArray@, @JSONObject@, @JSONArray@@String@, @byte[]@, plain C# object that can be converted to Json@String@, @StringBuffer@, @JSON Object@@String@, @[]byte@@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@@String@, @Bytearray@, @Dict@, @List@@String@, @NSData@, @Dictionary@, @Array@@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@@String@, @Binary String@, @Associative Array@, @Array@__ - -- extrasExtras := Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the "@push@":/docs/push/publish#sub-channels, "@ref@":/docs/channels/messages#interactions and "@privileged@":/docs/platform/integrations/webhooks#skipping objects.
__Type: @JSONObject@, @JSONArray@plain C# object that can be converted to Json@String@, @[]byte@@JSON Object@@Hash@, @Array@@Dict@, @List@@Dictionary@, @Array@@NSDictionary *@, @NSArray *@@Associative Array@, @Array@@Map@, @List@__ - -- idId := Unique ID assigned by Ably to this presence update
__Type: @String@__ - -- clientIdclient_idClientId := The client ID of the publisher of this presence update
__Type: @String@__ - -- connectionIdconnection_idConnectionId := The connection ID of the publisher of this presence update
__Type: @String@__ - -- timestampTimestamp := Timestamp when the presence update was received by Ably, as milliseconds since the epoch.
__Type: @Integer@@Long Integer@@DateTimeOffset@@Time@@NSDate@__ - -- encodingEncoding := This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the @data@ payload
__Type: @String@__ - -h3. - default: PresenceMessage constructors - -h4(#presence-from-encoded). - default: PresenceMessage.fromEncoded - -bq(definition). - default: PresenceMessage.fromEncoded(Object encodedPresMsg, ChannelOptions channelOptions?) -> PresenceMessage - -A static factory method to create a "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message from a deserialized @PresenceMessage@-like object encoded using Ably's wire protocol. - -h4. Parameters - -- encodedPresMsg := a @PresenceMessage@-like deserialized object.
__Type: @Object@__ -- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.
__Type: @Object@__ - -h4. Returns - -A "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message object - -h4(#presence-from-encoded-array). - default: PresenceMessage.fromEncodedArray - -bq(definition). - default: PresenceMessage.fromEncodedArray(Object[] encodedPresMsgs, ChannelOptions channelOptions?) -> PresenceMessage[] - -A static factory method to create an array of "@PresenceMessages@":/docs/api/realtime-sdk/types#presence-message from an array of deserialized @PresenceMessage@-like object encoded using Ably's wire protocol. - -h4. Parameters - -- encodedPresMsgs := an array of @PresenceMessage@-like deserialized objects.
__Type: @Array@__ -- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.
__Type: @Object@__ - -h4. Returns - -An @Array@ of "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message objects diff --git a/content/partials/types/_push_admin.textile b/content/partials/types/_push_admin.textile deleted file mode 100644 index 7e63c50abb..0000000000 --- a/content/partials/types/_push_admin.textile +++ /dev/null @@ -1,527 +0,0 @@ -h2(#push-admin). Push Admin object - -This object is accessible through @client.push.admin@ and provides: - -h3(#properties). - default: Push Admin Properties - ruby: Push::Admin Properties - -The push admin object exposes the following public propertiesattributesmembers: - -h6(#device-registrations). - default: deviceRegistrations - ruby,python: device_registrations - -The returned "@DeviceRegistrations@":#device-registrations-object object provides functionality for registering, updating, listing and de-registering push devices. - -h6(#channel-subscriptions). - default: channelSubscriptions - ruby,python: channel_subscriptions - -The returned "@PushChannelSubscriptions@":#push-channel-subscriptions object provides functionality for subscribing, listing and unsubscribing individual devices or groups of "identified devices":/docs/auth/identified-clients to push notifications published on channels. - -h3(#methods). Methods - -h6(#publish). - default: publish - -bq(definition). - default: publish(Object recipient, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err)) - jsall: publish(Object recipient, Object payload): Promise - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable publish(Hash recipient, Hash data) -> yield - python: publish(recipient=Object, data=Object) - php: publish(Array recipient, Array data) - swift,objc: publish(recipient: ARTPushRecipient, data: AnyObject?, callback: (("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?) -> Void)?) - java,android: void publish(String recipient, Object data, "CompletionListener":#completion-listener listener) - -Publishes a push notification directly to a device or group of devices sharing a "client identifier":/docs/auth/identified-clients. See the "push notification direct publishing documentation":/docs/push/publish#direct-publishing for more information. - -h4. Parameters - -- recipient := an objectan arraya Hash containing the push recipient details. See the "push notification publish REST API documentation":/docs/api/rest-api#push-publish for details on the supported recipient fields -- datapayload := an objectan arraya Hash containing the push notification data. See the "push admin payload structure":/docs/push/publish#payload for details on the supported push payload fields - --
&block
:= yielded upon success --
listener
:= Listener to be notified on completion
__Type: "@CompletionListener@":#completion-listener__ --
callback
:= called upon publishing the message, or with an error - -blang[jsall]. - h4. Returns - - Returns a promise. On success to publish the push notification, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - The callback is called upon success or failure to publish the push notification. When this operation fails, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[ruby]. - h4. Returns - - A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the method. - - On success, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method are yielded to. - - Failure to publish the push notification will trigger the @errback@ callback of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[java]. - h4. Listener result - - On successful publish of the message, the @onSuccess@ method of the "CompletionListener":#completion-listener is called. On failure to publish the message, the @onError@ method is called with an "@ErrorInfo@":#error-info argument describing the failure reason. - -h2(#device-registrations-object). - default: DeviceRegistrations object - jsall: PushDeviceRegistrations object - -This object is accessible through @client.push.admin.deviceRegistrations@@client.push.admin.device_registrations@ and provides an API to register new push notification devices, update existing devices, deregister old devices, and retrieve or list devices registered to an app. - -h3(#device-registrations-methods). Methods - -h6(#device-get). - default: get - -bq(definition#device-get-id). - default: get(String deviceId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "DeviceDetails":#device-details device)) - jsall: get(String deviceId): Promise<"DeviceDetails":#device-details> - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable get(String deviceId) -> yields "DeviceDetails":#device-details - python: "DeviceDetails":#device-details get(device_id=String) - php: "DeviceDetails":#device-details get(String deviceId) - swift,objc: get(deviceId: ArtDeviceId, callback: ((ARTDeviceDetails?, ARTErrorInfo?) -> Void)) - java,android: "DeviceDetails":#device-details get(String deviceId) - -blang[java,android]. - - bq(definition#device-get-id-async). - java,android: getAsync(String deviceId, Callback<"DeviceDetails":/docs/api/rest-sdk/push-admin#device-details> callback) - -bq(definition#device-get-device). - default: get("DeviceDetails":#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "DeviceDetails":#device-details device)) - jsall: get("DeviceDetails":#device-details deviceDetails): Promise<"DeviceDetails":#device-details> - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable get("DeviceDetails":#device-details device) -> yields "DeviceDetails":#device-details - -Obtain the @DeviceDetails@ for a device registered for receiving push registrations matching the @deviceId@ argument, or the @id@ attribute of the provided @DeviceDetails@ object. Requires @push-admin@ permission or @push-subscribe@ permission together with device authentication matching the requested @deviceId@. - -h4. Parameters - -- deviceId := the unique device ID String for the requested device -- devicedeviceDetails := a "@DeviceDetails@":#device-details object containing at a minimum the @deviceId@ of the requested device - --
&block
:= yields a @DeviceDetails@ object upon success - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@DeviceDetails@":#device-details object representing the device registered for push notifications. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - On success, @device@ contains the device registered for push notifications as a "@DeviceDetails@":#device-details object. - - On failure to retrieve the device, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[ruby]. - h4. Returns - - A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the method. - - On success, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method yield the device registered for push notifications as a "@DeviceDetails@":#device-details object. - - Failure to retrieve the device will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[java]. - h4. Listener result - - On successful publish of the message, the @onSuccess@ method of the "CompletionListener":#completion-listener is called. On failure to get the device, the @onError@ method is called with an "@ErrorInfo@":#error-info argument describing the failure reason. - -h6(#device-list). - default: list - -bq(definition). - default: list(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"DeviceDetails":#device-details device> resultPage)) - jsall: list(Object params): Promise<"PaginatedResult":#paginated-result<"DeviceDetails":#device-details>> - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable list(Hash params) -> yields "PaginatedResult":#paginated-result<"DeviceDetails":#device-details> - python: "PaginatedResult":#paginated-result list(params=Object) - php: "PaginatedResult":#paginated-result list_(Array params) - swift,objc: list(params: NSDictionary *, callback: (("ARTPaginatedResult":#paginated-result?, ARTErrorInfo?) -> Void)) - java,android: "PaginatedResult":#paginated-result list(Param[] params) - -Retrieve all devices matching the params filter as a paginated list of "@DeviceDetails@":#device-details objects. Requires @push-admin@ permission. - -h4. Parameters - -- params"Param":#param[] params := an object containing the query parameters as key value pairs as specified below. - --
&block
:= yields a @PaginatedResult@ object - -h4. @params@ properties - -- clientId:client_id := optional filter to restrict to devices associated with that client identifier. Cannot be used with a @deviceId@@:device_id@ param
__Type: @String@__ -- deviceId:device_id := optional filter to restrict to devices associated with that device identifier. Cannot be used with a @clientId@@:client_id@ param
__Type: @String@__ -- limit:limit := _100_ maximum number of devices per page to retrieve, up to 1,000
__Type: @Integer@__ - -blang[jsall]. - - state := optional filter by the state of the device. Must be one of @ACTIVE@, @FAILING@ or @FAILED@ __Type: @String@__ - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of "@DeviceDetails@":#device-details objects corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods. - - On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[objc,swift]. - h4. Callback result - - On success, @resultPage@ contains a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of "@DeviceDetails@":#device-details objects corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods. - - On failure to retrieve the devices, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[ruby]. - h4. Returns - - A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the method. - - On success, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method yield a "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result that encapsulates an array of "@DeviceDetails@":#device-details corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods. - - Failure to retrieve the devices will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -h6(#device-save). - default: save - -bq(definition). - default: save("DeviceDetails":#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "DeviceDetails":#device-details device)) - jsall: save("DeviceDetails":#device-details deviceDetails): Promise<"DeviceDetails":#device-details> - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable save("DeviceDetails":#device-details device) -> yields "DeviceDetails":#device-details - python: "DeviceDetails":#device-details save("DeviceDetails":#device-details device_details) - php: "DeviceDetails":#device-details save("DeviceDetails":#device-details deviceDetails) - swift,objc: save(deviceDetails: "DeviceDetails":#device-details, callback: (("DeviceDetails":#device-details?, ARTErrorInfo?) -> Void)) - java,android: "DeviceDetails":#device-details save("DeviceDetails":#device-details deviceDetails) - -Register a new @DeviceDetails@ object, or update an existing @DeviceDetails@ object with the Ably service. Requires @push-admin@ permission or @push-subscribe@ permission together with device authentication matching the requested @deviceId@. - -h4. Parameters - -- devicedeviceDetails := a "@DeviceDetails@":#device-details object - --
&block
:= yields the new @DeviceDetails@ object upon success - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@DeviceDetails@":#device-details object representing the newly registered or updated device. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - On success, @device@ contains the newly registered or updated device as a "@DeviceDetails@":#device-details object. - - On failure to create or update the device, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[ruby]. - h4. Returns - - A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the method. - - On success, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method yield the newly registered or updated device as a "@DeviceDetails@":#device-details object. - - Failure to create or update the device will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -h6(#device-remove). - default: remove - -bq(definition#device-remove-id). - default: remove(String deviceId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err)) - jsall: remove(String deviceId): Promise - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable remove(String deviceId) - python: remove(String device_id) - php: remove(String deviceId) - swift,objc: remove(deviceDetails: "DeviceDetails":#device-details, callback: (("DeviceDetails":#device-details?, ARTErrorInfo?) -> Void)) - java,android: "DeviceDetails":#device-details save("DeviceDetails":#device-details deviceDetails) - -bq(definition#device-remove-device). - default: remove("DeviceDetails":#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err)) - jsall: remove("DeviceDetails":#device-details deviceDetails): Promise - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable remove("DeviceDetails":#device-details device) -> yield - python: remove("DeviceDetails":#device-details device_details) - php: remove("DeviceDetails":#device-details deviceDetails) - swift,objc: remove(deviceDetails: "DeviceDetails":#device-details, callback: ((ARTErrorInfo?) -> Void)) - java,android: "DeviceDetails":#device-details save("DeviceDetails":#device-details deviceDetails) - -Remove a device registered for receiving push registrations that matches the @deviceId@ argument, or the @id@ attribute of the provided "@DeviceDetails@":#device-details object. Requires @push-admin@ permission or @push-subscribe@ permission together with device authentication matching the requested @deviceId@. - -h4. Parameters - -- deviceId := the unique device ID String for the device -- devicedeviceDetails := a "@DeviceDetails@":#device-details object containing at a minimum the @deviceId@ of the device - --
&block
:= yields upon success - -blang[jsall]. - h4. Returns - - Returns a promise. On success to delete the device, the promise resolves. Note that a request to delete a device that does not exist will result in a successful operation. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - The callback is called upon success or failure to delete the device. Note that a request to delete a device that does not exist will result in a successful operation. - - When this operation fails, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[ruby]. - h4. Returns - - A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the method. - - On success, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method are yielded to. Note that a request to delete a device that does not exist will result in a successful operation. - - Failure to delete the device will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -h6(#device-remove-where). - default: removeWhere - ruby,python: remove_where - -bq(definition). - default: removeWhere(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err)) - jsall: removeWhere(Object params): Promise - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable remove_where(Hash params) -> yield - python: remove_where(params=Object) - php: removeWhere(Array params) - swift,objc: removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) -> Void) - java,android: removeWhere(Param[] params) - -Delete all devices matching the params filter. Requires @push-admin@ permission. - -h4. Parameters - -- params"Param":#param[] params := an object containing the filter parameters as key value pairs as specified below. - --
&block
:= yields upon success - -h4. @params@ properties - -- clientId:client_id := optional filter to restrict to devices associated with that client identifier. Cannot be used with a @deviceId@@:device_id@ param
__Type: @String@__ -- deviceId:device_id := optional filter to restrict to devices associated with that device identifier. Cannot be used with a @clientId@@:client_id@ param
__Type: @String@__ - -blang[jsall]. - h4. Returns - - Returns a promise. On success to delete the device, the promise resolves. Note that a request that does match any existing devices will result in a successful operation. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - The callback is called upon success or failure to delete the device. Note that a request that does match any existing devices will result in a successful operation. - - When this operation fails, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[ruby]. - h4. Returns - - A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the method. - - On success, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method are yielded to. Note that a request that does match any existing devices will result in a successful operation. - - Failure to delete the device will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -h2(#push-channel-subscriptions). PushChannelSubscriptions object - -This object is accessible through @client.push.admin.channelSubscriptions@@client.push.admin.channel_subscriptions@ and provides an API to subscribe a push notification device to a channel ensuring it receives any push notifications published in the future on that channel. Additionally, this object allows these subscriptions to be retrieved, listed, updated or removed. - -h3(#push-channel-subscriptions-methods). Methods - -h6(#push-channel-sub-list). - default: list - -bq(definition). - default: list(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"PushChannelSubscription":#push-channel-subscription> resultPage)) - jsall: list(Object params): Promise<"PaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription>> - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable list(Hash params) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"PushChannelSubscription":#push-channel-subscription> - python: "PaginatedResult":#paginated-result list(params=Object) - php: "PaginatedResult":#paginated-result list_(Array params) - swift,objc: list(params: NSDictionary *, callback: (("ARTPaginatedResult":#paginated-result?, ARTErrorInfo?) -> Void)) - java,android: "PaginatedResult":#paginated-result list(Param[] params) - -Retrieve all push channel subscriptions that match the provided params filter as a paginated list of "@PushChannelSubscription@":#push-channel-subscription objects. Each "@PushChannelSubscription@":#push-channel-subscription represents a device or set of devices sharing the same "client identifier":/docs/auth/identified-clients registered to a channel to receive push notifications. - -h4. Parameters - -- params"Param":#param[] params := an object containing the query parameters as key value pairs as specified below. - --
&block
:= yields a @PaginatedResult@ object - -h4. @params@ properties - -- channel:channel := filter to restrict to subscriptions associated with that @channel@ -- clientId:client_id := optional filter to restrict to devices associated with that client identifier. Cannot be used with a @deviceId@@:device_id@ param
__Type: @String@__ -- deviceId:device_id := optional filter to restrict to devices associated with that device identifier. Cannot be used with a @clientId@@:client_id@ param
__Type: @String@__ -- limit:limit := _100_ maximum number of channel subscriptions per page to retrieve, up to 1,000
__Type: @Integer@__ - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of "@PushChannelSubscription@":#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods. - - On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - On success, @resultPage@ contains a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of "@PushChannelSubscription@":#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods. - - On failure to retrieve the channel subscriptions, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object which contains the failure reason. - -blang[ruby]. - h4. Returns - - A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the method. - - On success, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method yield a "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result that encapsulates an array of "@PushChannelSubscription@":#push-channel-subscription corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods. - - Failure to retrieve the channel subscriptions will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -h6(#push-channel-sub-list-channels). - default: listChannels - ruby,python: list_channels - -bq(definition). - default: listChannels(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result resultPage)) - jsall: listChannels(Object params): Promise<"PaginatedResult":#paginated-result> - ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable list_channels(Hash params) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result - python: "PaginatedResult":#paginated-result list_channels(params=Object) - php: "PaginatedResult":#paginated-result listChannels(Array params) - swift,objc: listChannels(params: NSDictionary *, callback: (("ARTPaginatedResult":#paginated-result?, ARTErrorInfo?) -> Void)) - java,android: "PaginatedResult":#paginated-result listChannels(Param[] params) - -Retrieve a list of channels that have at least one device "subscribed to push notifications":/docs/push/publish#sub-channels as a paginated list of channel name @String@ objects. Requires @push-admin@ permission. - -h4. Parameters - -- params"Param":#param[] params := an object containing the query parameters as key value pairs as specified below. - --
&block
:= yields a @PaginatedResult@ object - -h4. @params@ properties - -- limit:limit := _100_ maximum number of channels per page to retrieve, up to 1,000
__Type: @Integer@__ - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of channel name @String@ values corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods. - - On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - On success, @resultPage@ contains a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of channel name @String@ values corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods. - - On failure to retrieve the channels, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[ruby]. - h4. Returns - - A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the method. - - On success, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method yield a "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result that encapsulates an array of channel name @String@ values corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods. - - Failure to retrieve the channels will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -h6(#push-channel-sub-save). - default: save - -bq(definition). - default: save("PushChannelSubscription":#push-channel-subscription channelSubscription, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PushChannelSubscription":#push-channel-subscription channelSubscription)) - jsall: save("PushChannelSubscription":#push-channel-subscription subscription): Promise<"PushChannelSubscription":#push-channel-subscription> - ruby: save("PushChannelSubscription":#push-channel-subscription channel_subscription) - python: "PushChannelSubscription":#push-channel-subscription save("PushChannelSubscription":#push-channel-subscription channel_subscription) - php: "PushChannelSubscription":#push-channel-subscription save("PushChannelSubscription":#push-channel-subscription channelSubscription) - swift,objc: save(channelSubscription: "PushChannelSubscription":#push-channel-subscription, callback: (("PushChannelSubscription":#push-channel-subscription?, ARTErrorInfo?) -> Void)) - java,android: "PushChannelSubscription":#push-channel-subscription save("PushChannelSubscription":#push-channel-subscription channelSubscription) - -Subscribe a device or group of devices sharing a "client identifier":/docs/auth/identified-clients for push notifications published on a channel. - -h4. Parameters - -- channelSubscriptionsubscriptionchannel_subscription := a "@PushChannelSubscription@":#push-channel-subscription object - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@PushChannelSubscription@":#push-channel-subscription object representing the newly subscribed or updated push channel subscription. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - On success, @channelSubscription@ contains the newly subscribed or updated push channel subscription as a "@PushChannelSubscription@":#push-channel-subscription object. - - On failure to create or update the channel subscription, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -h6(#push-channel-sub-remove). - default: remove - -bq(definition). - default: remove("PushChannelSubscription":#push-channel-subscription channelSubscription, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err)) - jsall: remove("PushChannelSubscription":#push-channel-subscription subscription): Promise - ruby: remove("PushChannelSubscription":#push-channel-subscription channel_subscription) - python: remove("PushChannelSubscription":#push-channel-subscription channel_subscription) - php: remove("PushChannelSubscription":#push-channel-subscription subscription) - swift,objc: remove(channelSubscription: "PushChannelSubscription":#push-channel-subscription, callback: ((ARTErrorInfo?) -> Void)) - java,android: void save("PushChannelSubscription":#push-channel-subscription channelSubscription) - -Unsubscribe a device or group of devices sharing a "client identifier":/docs/auth/identified-clients from push notifications on a channel. Requires @push-admin@ permission or, in the case of a subscription associated with a given @deviceId@, @push-subscribe@ permission together with device authentication matching that @deviceId@. - -h4. Parameters - -- channelSubscriptionsubscriptionchannel_subscription := a "@PushChannelSubscription@":#push-channel-subscription object - -blang[jsall]. - h4. Returns - - Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - The callback is called upon success or failure to unsubscribe. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation. - - When this operation fails, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -h6(#push-channel-sub-remove-where). - default: removeWhere - ruby,python: remove_where - -bq(definition). - default: removeWhere(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err)) - jsall: removeWhere(Object params): Promise - ruby: remove_where(Hash params) - python: remove_where(params=Object) - php: removeWhere(Array params) - swift,objc: removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) -> Void) - java,android: removeWhere(Param[] params) - -Delete all push channel subscriptions matching the @params@ filter. Requires @push-admin@ permission. - -h4. Parameters - -- params"Param":#param[] params := an object containing the filter parameters as key value pairs as specified below. - -h4. @params@ properties - -- channel:channel := filter to restrict to subscriptions associated with that @channel@ -- clientId:client_id := optional filter to restrict to devices associated with that client identifier. Cannot be used with @deviceId@@:device_id@ param
__Type: @String@__ -- deviceId:device_id := optional filter to restrict to devices associated with that device identifier. Cannot be used with @clientId@@:client_id@ param
__Type: @String@__ - -blang[jsall]. - h4. Returns - - Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[swift,objc]. - h4. Callback result - - The callback is called upon success or failure to unsubscribe. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation. - - When this operation fails, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. diff --git a/content/partials/types/_push_channel.textile b/content/partials/types/_push_channel.textile deleted file mode 100644 index d5d2653ab8..0000000000 --- a/content/partials/types/_push_channel.textile +++ /dev/null @@ -1,100 +0,0 @@ -A @PushChannel@ is a property of a "@RealtimeChannel@":/docs/api/realtime-sdk/channels#properties or "@RestChannel@":/docs/api/rest-sdk/channels#properties. It provides "push devices":/docs/push the ability to subscribe and unsubscribe to push notifications on channels. - -h4. Methods - -h6(#subscribe-device). - default: subscribeDevice - -bq(definition). - default: subscribeDevice() - jsall: subscribeDevice(): Promise - -Subscribe your device to the channel's push notifications. - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -h6(#subscribe-client). - default: subscribeClient - -bq(definition). - default: subscribeClient() - jsall: subscribeClient(): Promise - -"Subscribe all devices associated with your device's clientId":/docs/push/publish#sub-channels to the channel's push notifications. - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -h6(#unsubscribe-device). - default: unsubscribeDevice - -bq(definition). - default: unsubscribeDevice() - jsall: unsubscribeDevice(): Promise - -Unsubscribe your device from the channel's push notifications. - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -h6(#unsubscribe-client). - default: unsubscribeClient - -bq(definition). - default: unsubscribeClient() - jsall: unsubscribeClient(): Promise - -"Unsubscribe all devices associated with your device's clientId":/docs/push/publish#sub-channels from the channel's push notifications. - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -h6(#list-subscriptions). - default: listSubscriptions - -bq(definition). - jsall: listSubscriptions(Record params?): Promise<"PaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription>>; - java,android: "PaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription> listSubscriptions(String deviceId, String clientId, String deviceClientId, String channel) - objc,swift: listSubscriptions(deviceId: String?, clientId: String?, deviceClientId: String?, `channel: String?, callback: ("ARTPaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription>?, ARTErrorInfo?) -> Void) - -Lists push subscriptions on a channel specified by its channel name (@channel@). These subscriptions can be either be a list of client (@clientId@) subscriptions, device (@deviceId@) subscriptions, or if @concatFilters@ is set to @true@, a list of both. This method requires clients to have the "Push Admin capability":push#push-admin. For more information, see @GET main.realtime.ably.net/push/channelSubscriptions@ "Rest API":/docs/api/rest-api. - -h4. Parameters - -- deviceId := a deviceId to filter by
__Type: @String@__ - -- clientId := a clientId to filter by
__Type: @String@__ - -- deviceClientId := a client ID associated with a device to filter by
__Type: @String@__ - --
callback
:= called with a "ARTPaginatedResult":#paginated-result<"PushChannelSubscription":/docs/api/realtime-sdk/push-admin#push-channel-subscription> object or an error - --
params
:= An optional object containing key-value pairs to filter subscriptions by. Can contain @clientId@, @deviceId@ or a combination of both, and a @limit@ on the number of subscriptions returned, up to 1,000
__Type: @Record@__ - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with "@PaginatedResult@":#paginated-result which encapsulates an array of "PushChannelSubscription":#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected. - -blang[objc,swift]. - h4. Callback result - - On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "PushChannelSubscription":/docs/api/realtime-sdk/push-admin#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods. - - On failure to retrieve message history, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason. - -blang[java,android]. - h4. Returns - - On success, the returned "@PaginatedResult@":#paginated-result encapsulates an array of "PushChannelSubscription":#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods. - - Failure to retrieve the message history will raise an "@AblyException@":/docs/api/realtime-sdk/types#ably-exception diff --git a/content/partials/types/_push_channel_subscription.textile b/content/partials/types/_push_channel_subscription.textile deleted file mode 100644 index 7679031cff..0000000000 --- a/content/partials/types/_push_channel_subscription.textile +++ /dev/null @@ -1,56 +0,0 @@ -An @PushChannelSubscription@ is a type encapsulating the subscription of a device or group of devices sharing a "client identifier":/docs/auth/identified-clients to a channel in order to receive push notifications. - -h4. - default: Properties - java: Members - ruby: Attributes - -- channel := the channel that this push notification subscription is associated with
__Type: @String@__ - -- deviceIddevice_id := the device with this identifier is linked to this channel subscription. When present, @clientId@@client_id@ is never present
__Type: @String@__ - -- clientIdclient_id := devices with this "client identifier":/docs/auth/identified-clients are included in this channel subscription. When present, @deviceId@@device_id@ is never present
__Type: @String@__ - -blang[jsall]. - -blang[default]. - h3. - default: PushChannelSubscription constructors - - h6(#push-channel-subscription-for-device). - default: PushChannelSubscription.forDevice - ruby: PushChannelSubscription.for_device - - bq(definition). - default: PushChannelSubscription.forDevice(String channel, String deviceId) -> PushChannelSubscription - ruby: PushChannelSubscription.for_device(String channel, String device_id) -> PushChannelSubscription - - A static factory method to create a @PushChannelSubscription@ object for a channel and single device. - - h4. Parameters - - - channel := channel name linked to this push channel subscription
__Type: @String@__ - - deviceIddevice_id := the device with this identifier will be linked with this push channel subscription
__Type: @String@__ - - h4. Returns - - A "@PushChannelSubscription@":/docs/api/realtime-sdk/types#push-channel-subscription object - - h6(#push-channel-subscription-for-client-id). - default: PushChannelSubscription.forClient - ruby: PushChannelSubscription.for_client - - bq(definition). - default: PushChannelSubscription.forClient(String channel, String clientId) -> PushChannelSubscription - ruby: PushChannelSubscription.for_client(String channel, String client_id) -> PushChannelSubscription - - A static factory method to create a @PushChannelSubscription@ object for a channel and group of devices sharing a "client identifier":/docs/auth/identified-clients. - - h4. Parameters - - - channel := channel name linked to this push channel subscription
__Type: @String@__ - - clientIdclient_id := devices with this "client identifier":/docs/auth/identified-clients are included in the new push channel subscription
__Type: @String@__ - - h4. Returns - - A @PushChannelSubscription@ object diff --git a/content/partials/types/_push_device.textile b/content/partials/types/_push_device.textile deleted file mode 100644 index 28f761170a..0000000000 --- a/content/partials/types/_push_device.textile +++ /dev/null @@ -1,51 +0,0 @@ -h2(#push-object). Push Device object - -This object is accessible through @client.push@ and provides to "push-compatible devices":/docs/push : - -h3. Methods - -h6(#activate). - default: activate - -bq(definition). - android: void activate() - objc,swift: activate(callback: ("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?, DeviceDetails?) -> Void) - jsall: activate(registerCallback?("DeviceDetails":/docs/api/realtime-sdk/types#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info | null err, "DeviceDetails":/docs/api/realtime-sdk/types#device-details result)), updateFailedCallback?("ErrorInfo":/docs/api/realtime-sdk/types#error-info | null err)): Promise - -blang[default]. - Register the device for push. When the "activation process":/docs/push/configure/device#activate-devices is completed, Ably will send a broadcast through the application's "@LocalBroadcastManager@":https://developer.android.com/reference/android/support/v4/content/LocalBroadcastManager. Success or failure will be broadcast through @io.ably.broadcast.PUSH_ACTIVATE@call the @(void)didActivateAblyPush:(nullable ARTErrorInfo *)error@@didActivateAblyPush(error: ARTErrorInfo?)@ method from the @ARTPushRegistererDelegate@. - -blang[jsall]. - "Activates the device":/docs/push/configure/web#activate-browsers for push notifications. Subsequently registers the device with Ably and stores the @deviceIdentityToken@ in local storage. - - h4. Parameters - - - registerCallback := An optional function passed to override the default implementation to register the local device for push activation__Type: @Callable@__ - - - updateFailedCallback := An optional callback to be invoked when the device registration failed to update
__Type: @Callable@__ - - h4. Returns - - Returns a promise. On successful device activation, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object that details the reason why it was rejected. - -h6(#deactivate). - default: deactivate - -bq(definition). - android: void deactivate() - objc,swift: deactivate(deregisterCallback: ("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?, deviceId: String?) -> Void) - jsall: deactivate(deregisterCallback?("DeviceDetails":/docs/api/realtime-sdk/types#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info | null err, String result))): Promise - -blang[default]. - Deregister the device for push. When the deactivation process is completed, Ably will send a broadcast through the application's "@LocalBroadcastManager@":https://developer.android.com/reference/android/support/v4/content/LocalBroadcastManager. Success or failure will be broadcast through @io.ably.broadcast.PUSH_DEACTIVATE@call the @(void)didDeactivateAblyPush:(nullable ARTErrorInfo *)error@@didDeactivateAblyPush(error: ARTErrorInfo?)@ method from the@ARTPushRegistererDelegate@. - -blang[jsall]. - Deactivates the device from receiving push notifications. - - h4. Parameters - - - deregisterCallback := An optional function passed to override the default implementation to deregister the local device for push activation__Type: @Callable@__ - - h4. Returns - - Returns a promise. On successful device deactivation, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object that details the reason why it was rejected. diff --git a/content/partials/types/_realtime_client_options.textile b/content/partials/types/_realtime_client_options.textile deleted file mode 100644 index 0258dd4e79..0000000000 --- a/content/partials/types/_realtime_client_options.textile +++ /dev/null @@ -1,22 +0,0 @@ -- queueMessagesQueueMessages:queue_messages := _true_ If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior allows applications to submit messages immediately upon instancing the library without having to wait for the connection to be established. Applications may use this option to disable queueing if they wish to have application-level control over the queueing under those conditions
__Type: @Boolean@__ - -- echoMessagesEchoMessages:echo_messages := _true_ If false, prevents messages originating from this connection being echoed back on the same connection
__Type: @Boolean@__ - -- autoConnectAutoConnect:auto_connect := _true_ By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the "@connect@":/docs/api/realtime-sdk/connection#connect method
__Type: @Boolean@__ - --
recover
:= This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might typically be used by clients of the browser library to ensure connection state can be preserved when the user refreshes the page. A recovery key string can be explicitly provided, or alternatively if a callback function is provided, the client library will automatically persist the recovery key between page reloads and call the callback when the connection is recoverable. The callback is then responsible for confirming whether the connection should be recovered or not. See "connection state recovery":/docs/connect/states for further information
__Type: @String@, @Callable@__ - --
closeOnUnload
:= _true_ When true, the client library will automatically send a close request to Ably whenever the @window beforeunload@ event fires. By enabling this option, the close request sent to Ably ensures the connection state will not be retained and all channels associated with the connection will be detached. This is commonly used by developers who want presence leave events to fire immediately i.e. if a user navigates to another page or closes their browser, then enabling this option will result in the presence member leaving immediately. Without this option or an explicit call to the "@close@":/docs/api/realtime-sdk/connection#close method of the "@Connection object@":/docs/api/realtime-sdk/connection, Ably expects that the abruptly disconnected connection could later be recovered and therefore does not immediately remove the user from presence. Instead, to avoid "twitchy" presence behavior an abruptly disconnected client is removed from channels in which they are present after 15 seconds, and the connection state is retained for two minutes
__Type: @Boolean@__ - --
recoverRecover:recover
:= This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's "@recoveryKey@":/docs/api/realtime-sdk/connection#recovery-key"@recovery_key@":/docs/api/realtime-sdk/connection#recovery-key. This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See "connection state recovery":/docs/connect/states for further information and example code
__Type: @String@__ - -- queryTimeQueryTime:query_time := _false_ If true, the library will query the Ably servers for the current time when "issuing TokenRequests":/docs/auth/token instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably "TokenRequests":/docs/api/realtime-sdk/authentication#request-token, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an "NTP daemon":https://en.wikipedia.org/wiki/Ntpd . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
__Type: @Boolean@__ - -- defaultTokenParamsDefaultTokenParams:default_token_params := When a "TokenParams":/docs/api/realtime-sdk/types#token-params object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests
__Type: "@TokenParams@":/docs/api/realtime-sdk/types#token-params__ - -- disconnectedRetryTimeoutDisconnectedRetryTimeout:disconnected_retry_timeout := _15,000ms15s_ When the connection enters the @DISCONNECTED@ state, after this delay in millisecondsin secondsas a @NSTimeInterval@, if the state is still @DISCONNECTED@, the client library will attempt to reconnect automatically
__Type: @Integer@@NSTimeInterval@__ - -- suspendedRetryTimeoutSuspendedRetryTimeout:suspended_retry_timeout := _30,000ms30s_ When the connection enters the @SUSPENDED@ state, after this delay in millisecondsin secondsas a @NSTimeInterval@, if the state is still @SUSPENDED@, the client library will attempt to reconnect automatically
__Type: @Integer@@NSTimeInterval@__ - -blang[jsall]. - - pushServiceWorkerUrl := A URL pointing to a service worker script which is used as the target for web push notifications
__Type: @String@__ diff --git a/content/partials/types/_realtime_client_options_intro.textile b/content/partials/types/_realtime_client_options_intro.textile deleted file mode 100644 index 818462e4c0..0000000000 --- a/content/partials/types/_realtime_client_options_intro.textile +++ /dev/null @@ -1,12 +0,0 @@ -blang[jsall]. - @ClientOptions@ is a plain JavaScript object and is used in the @Ably.Realtime@ constructor's @options@ argument. The following attributes can be defined on the object: - -blang[ruby]. - @ClientOptions@ is a Hash object and is used in the @Ably::Realtime@ constructor's @options@ argument. The following key symbol values can be added to the Hash: - -blang[php]. - @ClientOptions@ is a associative array and is used in the @Ably\AblyRealtime@ constructor's @options@ argument. The following named keys and values can be added to the associative array: - -blang[java,objc,swift,csharp,go,flutter]. - @ART@@ClientOptions@ is used in the @AblyRealtime@ constructor's @options@ argument. - diff --git a/content/partials/types/_rest_client_options.textile b/content/partials/types/_rest_client_options.textile deleted file mode 100644 index 38609231e7..0000000000 --- a/content/partials/types/_rest_client_options.textile +++ /dev/null @@ -1,3 +0,0 @@ -- queryTimeQueryTime:query_timequery_time := _false_ If true, the library will query the Ably servers for the current time when "issuing TokenRequests":/docs/auth/token instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably "TokenRequests":/docs/api/rest-sdk/authentication#token-request, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an "NTP daemon":https://en.wikipedia.org/wiki/Ntpd . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
__Type: @Boolean@__ - -- defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams := When a "TokenParams":/docs/api/rest-sdk/types#token-params object is provided, it will override the client library defaults when issuing new "Ably Tokens":/docs/api/realtime-sdk/authentication#token-details or "Ably @TokenRequests@":/docs/api/rest-sdk/authentication#token-request
__Type: "@TokenParams@":/docs/api/rest-sdk/types#token-params__ diff --git a/content/partials/types/_rest_client_options_intro.textile b/content/partials/types/_rest_client_options_intro.textile deleted file mode 100644 index 810b3d2d22..0000000000 --- a/content/partials/types/_rest_client_options_intro.textile +++ /dev/null @@ -1,14 +0,0 @@ -blang[jsall]. - @ClientOptions@ is a plain JavaScript object and is used in the @Ably.Rest@ constructor's @options@ argument. The following attributes can be defined on the object: - -blang[ruby]. - @ClientOptions@ is a Hash object and is used in the @Ably::Rest@ constructor's @options@ argument. The following key symbol values can be added to the Hash: - -blang[php]. - @ClientOptions@ is a associative array and is used in the @Ably\AblyRest@ constructor's @options@ argument. The following named keys and values can be added to the associative array: - -blang[java,objc,swift,csharp,go]. - @ART@@ClientOptions@ is used in the @AblyRest@ constructor's @options@ argument. - -blang[flutter]. - @ably.ClientOptions@ is used in the @ably.Rest@ constructor's @options@ named argument diff --git a/content/partials/types/_stats.textile b/content/partials/types/_stats.textile deleted file mode 100644 index 62ea980410..0000000000 --- a/content/partials/types/_stats.textile +++ /dev/null @@ -1,37 +0,0 @@ -A @Stats@ object represents an application's statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our "statistics API":/docs/metadata-stats/stats as well as your "application dashboard":https://ably.com/dashboard. - -
-
-Please note that most attributes of the @Stats@ type below contain references to further stats types. This documentation is not exhaustive for all stats types, and as such, links to the stats types below will take you to the "Ruby library stats documentation":https://www.rubydoc.info/gems/ably/Ably/Models/Stats which contains exhaustive stats documentation. Ruby and Python however uses @under_score@ case instead of the default @camelCase@ in most languages, so please bear that in mind. -
- -h4. - default: Properties - java: Members - ruby: Attributes - python: Keyword arguments - -blang[default]. - - unit := the length of the interval that this statistic covers, such as @:minute@, @:hour@, @:day@, @:month@@Minute@, @Hour@, @Day@, @Month@@StatGranularityDay@, @StatGranularityMonth@@'minute'@, @'hour'@, @'day'@, @'month'@.
__Type: "@Stats::GRANULARITY@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant"@StatsIntervalGranularity@":/docs/api/realtime-sdk/types#stats-granularity enum@ARTStatsGranularity@@String@__ - -
interval_granularityintervalGranularity
:= Deprecated alias for @unit@; scheduled to be removed in version 2.x client library versions.
__Type: "@Stats::GRANULARITY@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant"@StatsIntervalGranularity@":/docs/api/realtime-sdk/types#stats-granularity enum@ARTStatsGranularity@@String@__ - - intervalIdinterval_idIntervalId := the UTC time at which the time period covered by this @Stats@ object starts. For example, an interval ID value of "2018-03-01:10" in a @Stats@ object whose @unit@ is @day@ would indicate that the period covered is "2018-03-01:10 .. 2018-03-01:11". All @Stats@ objects, except those whose @unit@ is @minute@, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer the @unit@ by looking at the resolution of the @intervalId@. @Stats@ objects covering an individual minute will have an interval ID indicating that time; for example "2018-03-01:10:02".
__Type: @String@__ - -
interval_timeIntervalTime
:= A @Time@@DateTime@@DateTimeOffset@ object representing the parsed @intervalId@@interval_id@@IntervalId@ (the UTC time at which the time period covered by this @Stats@ object starts)
__Type: @Time@@DateTime@@DateTimeOffset@__ - - allAll := aggregate count of both @inbound@ and @outbound@ message stats
__Type: "@MessageTypes@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes__ - - apiRequestsapi_requestsApiRequests := breakdown of API requests received via the Ably REST API
__Type: "@RequestCount@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount__ - - channelsChannels := breakdown of channel related stats such as min, mean and peak channels
__Type: "@ResourceCount@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount__ - - connectionsConnections := breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections
__Type: "@ConnectionTypes@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ConnectionTypes__ - - inboundInbound := statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages
__Type: "@MessageTraffic@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic__ - - outboundOutbound := statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with Webhooks, organized into normal channel messages or presence messages
__Type: "@MessageTraffic@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic__ - - persistedPersisted := messages persisted and later retrieved via the "history API":/docs/storage-history/history
__Type: "@MessageTypes@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes__ - - tokenRequeststoken_requestsTokenRequests := breakdown of Ably Token requests received via the Ably REST API.
__Type: "@RequestCount@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount__ - - pushPush := Detailed stats on push notifications, see "our Push documentation":/push for more details
__Type: @PushStats@__ - -blang[jsall]. - - appId := the ID of the Ably application the statistics relate to.
__Type: @String@__ - - entries := The statistics for the requested time interval and time period. The @schema@ property provides further information
__Type: @Partial>@__ - - inProgress := Optional. For entires that are still in progress, such as the current month, the last sub-interval included in the stats entry. In the format @yyyy-mm-dd:hh:mm:ss@
__Type: @String@__ - - intervalId := The UTC time period that the stats coverage begins at. If @unit@ was requested as @minute@ this will be in the format @YYYY-mm-dd:HH:MM@, if @hour@ it will be @YYYY-mm-dd:HH@, if @day@ it will be @YYYY-mm-dd:00@ and if @month@ it will be @YYYY-mm-01:00@
__Type: @String@__ - - schema := The URL of a JSON schema describing the structure of the @Stats@ object
__Type: @String@__ - - - diff --git a/content/partials/types/_stats_granularity.textile b/content/partials/types/_stats_granularity.textile deleted file mode 100644 index d61f1bbe35..0000000000 --- a/content/partials/types/_stats_granularity.textile +++ /dev/null @@ -1,45 +0,0 @@ -blang[jsall]. - @StatsIntervalGranularity@ is an enum specifying the granularity of a "@Stats interval@":/docs/api/rest-sdk/statistics#stats-type. - - ```[javascript] - const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' - ] - ``` - -blang[swift,objc]. - @ARTStatsGranularity@ is an enum specifying the granularity of a "@ARTStats interval@":/docs/api/rest-sdk/statistics#stats-type. - - ```[objc] - typedef NS_ENUM(NSUInteger, ARTStatsGranularity) { - ARTStatsGranularityMinute, - ARTStatsGranularityHour, - ARTStatsGranularityDay, - ARTStatsGranularityMonth - }; - ``` - - ```[swift] - enum ARTStatsGranularity : UInt { - case Minute - case Hour - case Day - case Month - } - ``` - -blang[csharp]. - @StatsIntervalGranularity@ is an enum specifying the granularity of a "@Stats interval@":/docs/api/rest-sdk/statistics#stats-type. - - ```[csharp] - public enum StatsIntervalGranularity - { - Minute, - Hour, - Day, - Month - } - ``` diff --git a/content/partials/types/_stats_request_params.textile b/content/partials/types/_stats_request_params.textile deleted file mode 100644 index bbbd613b12..0000000000 --- a/content/partials/types/_stats_request_params.textile +++ /dev/null @@ -1,10 +0,0 @@ -@StatsRequestParams@ is a type that encapsulates the parameters for a stats query. For example usage see "@Realtime#stats@@Realtime#Stats@":/docs/metadata-stats/stats. - -h4. Members - -- Start := _null_ The start of the queried interval
__Type: @DateTimeOffset@__ -- End := _null_ The end of the queried interval
__Type: @DateTimeOffset@__ -- Limit := _null_ By default it is null. Limits the number of items returned by history or stats
__Type: @Integer@__ -- Direction := _Backwards_ Enum which is either @Forwards@ or @Backwards@
__Type: @Direction@ enum__ -- Unit := _Minute_ @Minute@, @Hour@, @Day@ @Month@. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query
__Type: "@StatsIntervalGranularity@":/docs/api/realtime-sdk/types#stats-granularity enum__ -- ExtraParameters := Optionally any extra query parameters that may be passed to the query. This is mainly used internally by the library to manage paging.
__Type: @Dictionary@__ diff --git a/content/partials/types/_token_details.textile b/content/partials/types/_token_details.textile deleted file mode 100644 index 4b2703b9e1..0000000000 --- a/content/partials/types/_token_details.textile +++ /dev/null @@ -1,55 +0,0 @@ -@TokenDetails@ is a type providing details of Ably Token string and its associated metadata. - -h4. - default: Properties - java: Members - ruby: Attributes - -- tokenToken := The "Ably Token":/docs/api/realtime-sdk/authentication#token-details itself. A typical "Ably Token":/docs/api/realtime-sdk/authentication#token-details string may appear like @{{TOKEN}}@
__Type: @String@__ -- expiresExpires := The time (in milliseconds since the epoch)The time at which this token expires
__Type: @Integer@@Long Integer@@DateTimeOffset@@Time@@NSDate@__ -- issuedIssued := The time (in milliseconds since the epoch)The time at which this token was issued
__Type: @Integer@@Long Integer@@DateTimeOffset@@Time@@NSDate@__ -- capabilityCapability := The capability associated with this "Ably Token":/docs/api/realtime-sdk/authentication#token-details. The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. "Read more about authentication and capabilities":/docs/auth/capabilities
__Type: @String@@Capability@__ -- clientIdclient_idClientId := The client ID, if any, bound to this "Ably Token":/docs/api/realtime-sdk/authentication#token-details. If a client ID is included, then the "Ably Token":/docs/api/realtime-sdk/authentication#token-details authenticates its bearer as that client ID, and the "Ably Token":/docs/api/realtime-sdk/authentication#token-details may only be used to perform operations on behalf of that client ID. The client is then considered to be an "identified client":/docs/auth/identified-clients
__Type: @String@__ - -blang[ruby]. - h3. Methods - - - expired? := True when the token has expired
__Type: @Boolean@__ - -blang[python]. - h3. Methods - - - is_expired() := True when the token has expired
__Type: @Boolean@__ - -blang[csharp]. - h3. Methods - - - IsValidToken() := True if the token has not expired
__Type: @Boolean@__ - -h3. - default: TokenDetails constructors - -h4(#token-details-from-json). - default: TokenDetails.fromJson - ruby: TokenDetails.from_json - flutter: TokenDetails.fromMap - -bq(definition). - default: TokenDetails.fromJson(String json) -> TokenDetails - ruby: TokenDetails.from_json(String json) -> TokenDetails - flutter: TokenDetails.fromMap(Map map) - -A static factory methodnamed constructor to create a "@TokenDetails@":/docs/api/realtime-sdk/types#token-details from a deserialized @TokenDetails@-like object or a JSON stringified @TokenDetails@map. This method is provided to minimize bugs as a result of differing types by platform for fields such as @timestamp@ or @ttl@. For example, in Ruby @ttl@ in the @TokenDetails@ object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using @to_json@ it is automatically converted to the Ably standard which is milliseconds. By using the @fromJson@@fromMap@ method when constructing a @TokenDetails@, Ably ensures that all fields are consistently serialized and deserialized across platforms. - -h4. Parameters - -blang[default]. - - json := a @TokenDetails@-like deserialized object or JSON stringified @TokenDetails@.
__Type: @Object, String@__ - -blang[flutter]. - - map := a @TokenDetails@-like deserialized map.
__Type: @Map@__ - - -h4. Returns - -A "@TokenDetails@":/docs/api/realtime-sdk/types#token-details object diff --git a/content/partials/types/_token_params.textile b/content/partials/types/_token_params.textile deleted file mode 100644 index 4ae27b1499..0000000000 --- a/content/partials/types/_token_params.textile +++ /dev/null @@ -1,33 +0,0 @@ -blang[jsall]. - @TokenParams@ is a plain JavaScript object and is used in the parameters of "token authentication":/docs/auth/token requests, corresponding to the desired attributes of the "Ably Token":/docs/api/realtime-sdk/authentication#token-details. The following attributes can be defined on the object: - -blang[ruby]. - @TokenParams@ is a Hash object and is used in the parameters of "token authentication":/docs/auth/token requests, corresponding to the desired attributes of the "Ably Token":/docs/api/realtime-sdk/authentication#token-details. The following key symbol values can be added to the Hash: - -blang[python]. - @TokenParams@ is a Dict and is used in the parameters of "token authentication":/docs/auth/token requests, corresponding to the desired attributes of the "Ably Token":/docs/api/realtime-sdk/authentication#token-details. The following keys-value pairs can be added to the Dict: - -blang[php]. - @TokenParams@ is an Associative Array and is used in the parameters of "token authentication":/docs/auth/token requests, corresponding to the desired attributes of the "Ably Token":/docs/api/realtime-sdk/authentication#token-details. The following named keys and values can be added to the Associative Array: - -blang[java,csharp]. - @TokenParams@ is used in the parameters of "token authentication":/docs/auth/token requests, corresponding to the desired attributes of the "Ably Token":/docs/api/realtime-sdk/authentication#token-details. - -blang[objc,swift]. - @ARTTokenParams@ is used in the parameters of "token authentication":/docs/auth/token requests, corresponding to the desired attributes of the "Ably Token":/docs/api/realtime-sdk/authentication#token-details. - -h4. - default: Properties - java: Members - ruby: Attributes - python: Attributes - -- capabilityCapability:capability := JSON stringified capability of the "Ably Token":/docs/api/realtime-sdk/authentication#token-details. If the "Ably Token":/docs/api/realtime-sdk/authentication#token-details request is successful, the capability of the returned "Ably Token":/docs/api/realtime-sdk/authentication#token-details will be the intersection of this capability with the capability of the issuing key. "Find our more about how to use capabilities to manage access privileges for clients":/docs/auth/capabilities. __Type: @String@@Capability@__ - -- clientIdClientIdclient_id:client_id := A client ID, used for identifying this client when publishing messages or for presence purposes. The @clientId@@client_id@@ClientId@ can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a @clientId@@client_id@@ClientId@ may also be implicit in a token used to instantiate the library; an error will be raised if a @clientId@@client_id@@ClientId@ specified here conflicts with the @clientId@@client_id@@ClientId@ implicit in the token. "Find out more about client identities":/docs/auth/identified-clients
__Type: @String@__ - -- nonceNonce:nonce := An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected.
__Type: @String@__ - -- timestampTimestamp:timestamp := The timestamp (in milliseconds since the epoch)The timestamp of this request. @timestamp@, in conjunction with the @nonce@, is used to prevent requests for "Ably Token":/docs/api/realtime-sdk/authentication#token-details from being replayed.
__Type: @Integer@@Long Integer@@Time@@NSDate@@DateTimeOffset@@DateTime@__ - -- ttlTtl:ttl := _1 hour_ Requested time to live for the "Ably Token":/docs/api/realtime-sdk/authentication#token-details being created in millisecondsin secondsas a @NSTimeInterval@as a @TimeSpan@. When omitted, the Ably REST API default of 60 minutes is applied by Ably
__Type: @Integer@ (milliseconds)@Integer@ (seconds)@NSTimeInterval@@Long Integer@@TimeSpan@__ diff --git a/content/partials/types/_token_request.textile b/content/partials/types/_token_request.textile deleted file mode 100644 index b0f9706aec..0000000000 --- a/content/partials/types/_token_request.textile +++ /dev/null @@ -1,41 +0,0 @@ -@TokenRequest@ is a type containing parameters for an Ably @TokenRequest@. "Ably Tokens":/docs/api/realtime-sdk/authentication#token-details are requested using "Auth#requestToken":/docs/api/rest-sdk/authentication#request-token"Auth#request_token":/docs/api/rest-sdk/authentication#request-token - -h4. - default: Properties - java: Members - ruby: Attributes - -- keyNamekey_nameKeyName := The key name of the key against which this request is made. The key name is public, whereas the key secret is private
__Type: @String@__ -- ttlTtl := Requested time to live for the "Ably Token":/docs/api/realtime-sdk/authentication#token-details in millisecondsin secondsas a @TimeSpan@. If the Ably @TokenRequest@ is successful, the TTL of the returned "Ably Token":/docs/api/realtime-sdk/authentication#token-details will be less than or equal to this value depending on application settings and the attributes of the issuing key.
__Type: @Integer@@TimeSpan@@NSTimeInterval@__ -- timestampTimestamp := The timestamp of this request in milliseconds
__Type: @Integer@@Long Integer@@Time@@DateTimeOffset@@NSDate@__ -- capabilityCapability := Capability of the requested "Ably Token":/docs/api/realtime-sdk/authentication#token-details. If the Ably @TokenRequest@ is successful, the capability of the returned "Ably Token":/docs/api/realtime-sdk/authentication#token-details will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. "Read more about authentication and capabilities":/docs/auth
__Type: @String@__ -- clientIdclient_idClientId := The client ID to associate with the requested "Ably Token":/docs/api/realtime-sdk/authentication#token-details. When provided, the "Ably Token":/docs/api/realtime-sdk/authentication#token-details may only be used to perform operations on behalf of that client ID
__Type: @String@__ -- nonceNonce := An opaque nonce string of at least 16 characters
__Type: @String@__ -- macMac := The Message Authentication Code for this request
__Type: @String@__ - -h3. - default: TokenRequest constructors - -h4(#token-request-from-json). - default: TokenRequest.fromJson - ruby: TokenRequest.from_json - flutter: TokenRequest.fromMap - -bq(definition). - default: TokenRequest.fromJson(String json) -> TokenRequest - ruby: TokenRequest.from_json(String json) -> TokenRequest - flutter: TokenRequest.fromMap(Map map) - -A static factory methodnamed constructor to create a "@TokenRequest@":/docs/api/realtime-sdk/types#token-request from a deserialized @TokenRequest@-like object or a JSON stringified @TokenRequest@/span>map. This method is provided to minimize bugs as a result of differing types by platform for fields such as @timestamp@ or @ttl@. For example, in Ruby @ttl@ in the @TokenRequest@ object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using @to_json@ it is automatically converted to the Ably standard which is milliseconds. By using the @fromJson@@fromMap@ method when constructing a @TokenRequest@, Ably ensures that all fields are consistently serialized and deserialized across platforms. - -h4. Parameters - -blang[default]. - - json := a @TokenRequest@-like deserialized object or JSON stringified @TokenRequest@.
__Type: @Object, String@__ - -blang[flutter]. - - map := a @TokenRequest@-like deserialized map.
__Type: @Map@__ - -h4. Returns - -A "@TokenRequest@":/docs/api/realtime-sdk/types#token-request object diff --git a/content/partials/types/_token_revocation_failure_result.textile b/content/partials/types/_token_revocation_failure_result.textile deleted file mode 100644 index 369e6e3b84..0000000000 --- a/content/partials/types/_token_revocation_failure_result.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @TokenRevocationFailureResult@ contains information about the result of an unsuccessful token revocation request for a single target specifier. - -h4. - default: Properties - -- target := The target specifier
__Type: @String@__ - -- error := Describes the reason for which token revocation failed for the given `target` as an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object
__Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__ diff --git a/content/partials/types/_token_revocation_options.textile b/content/partials/types/_token_revocation_options.textile deleted file mode 100644 index fe57c33c97..0000000000 --- a/content/partials/types/_token_revocation_options.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @TokenRevocationOptions@ describes the additional options accepted by revoke tokens request. - -h4. - default: Properties - -- issuedBefore := An optional Unix timestamp in milliseconds where only tokens issued before this time are revoked. The default is the current time. Requests with an @issuedBefore@ in the future, or more than an hour in the past, will be rejected
__Type: @Number@__ - -- allowReauthMargin := _false_ If true, permits a token renewal cycle to take place without needing established connections to be dropped, by postponing enforcement to 30 seconds in the future, and sending any existing connections a hint to obtain (and upgrade the connection to use) a new token. The default is @false@, meaning that the effect is near-immediate.
__Type: @Boolean@__ diff --git a/content/partials/types/_token_revocation_success_result.textile b/content/partials/types/_token_revocation_success_result.textile deleted file mode 100644 index 2cee5a8577..0000000000 --- a/content/partials/types/_token_revocation_success_result.textile +++ /dev/null @@ -1,10 +0,0 @@ -A @TokenRevocationSuccessResult@ contains information about the result of a successful token revocation request for a single target specifier. - -h4. - default: Properties - -- target := The target specifier
__Type: @String@__ - -- appliesAt := The time at which the token revocation will take effect, as a Unix timestamp in milliseconds
__Type: @Number@__ - -- issuedBefore := A Unix timestamp in milliseconds. Only tokens issued earlier than this time will be revoked
__Type: @Number@__ diff --git a/content/partials/types/_token_revocation_target_specifier.textile b/content/partials/types/_token_revocation_target_specifier.textile deleted file mode 100644 index fbbf9e986d..0000000000 --- a/content/partials/types/_token_revocation_target_specifier.textile +++ /dev/null @@ -1,8 +0,0 @@ -A @TokenRevocationTargetSpecifier@ describes which tokens should be affected by a token revocation request. - -h4. - default: Properties - -- type := The type of token revocation target specifier. Valid values include @clientId@, @revocationKey@ and @channel@
__Type: @String@__ - -- value := The value of the token revocation target specifier
__Type: @String@__ diff --git a/index.textile b/index.textile deleted file mode 100644 index eed05448d5..0000000000 --- a/index.textile +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Ably API Documentation -meta_description: "An introduction to the Ably documentation site." -section: none -hide_from_website: true ---- - -h1. Ably Github Documentation (Preview) - -p. The definitive stable version of the "Ably realtime messaging documentation":https://ably.com/docs can be found at "https://ably.com/docs":https://ably.com/docs. - -This documentation is a static site generated from the Github repository at "https://github.com/ably/docs":https://github.com/ably/docs. Anyone can fork this documentation and contributions can be made via pull requests. All changes in this repository will be merged into the definitive "Ably documentation":https://ably.com/docs periodically. - -* "Fork this documentation now »":https://github.com/ably/docs -* "Notify of us of an issue with this documentation »":https://github.com/ably/docs/issues - -h2. What's covered - -The Ably documentation is organized as follows: - -* "Getting started":/docs/getting-started -* "Realtime client library API documentation":/docs/realtime/ -* "REST client library API documentation":/docs/rest/ -* "REST API documentation":/docs/rest-api/. Note, we recommend you use one of our REST client libraries instead of accessing the Ably REST API directly as the client libraries abstract away underlying complexity and provide a rich convenient feature set to developers. -* More detail behind some of Ably's key features: "Authentication":/docs/auth, "Channel rules and namespaces":/docs/general/channel-rules-namespaces/, "Receiving Webhooks":/docs/general/webhooks, and "Application statistics":/docs/general/statistics/ -* Documentation targeted at client library developers including "Protocol documentation":/docs/client-lib-development-guide/protocol/, details on "Encryption":/docs/client-lib-development-guide/encryption/, and "our fallback mechanisms to ensure we can deliver on our uptime guarantee":/docs/client-lib-development-guide/connection-fallback/. Unless you are developing or extending an existing Ably client library, this documentation is most likely more low level than is needed for you to use the Ably realtime message service. - ---- - -"Contact us":https://ably.com/contact if you have any questions or suggestions. From 2154c7b163130b61ed8070f8acb0f37ae8cd6938 Mon Sep 17 00:00:00 2001 From: Kenneth Kalmer Date: Wed, 26 Nov 2025 21:55:38 +0000 Subject: [PATCH 4/6] Remove textile-js dependency and Gatsby config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove all packages and configuration related to textile processing now that textile support has been completely removed from the codebase. Packages removed: - textile-js: Textile markup language parser - turndown: HTML to Markdown converter (used in textile debugging) - diff: Text diffing library (used in textile debugging) - @types/turndown: TypeScript types for turndown - @types/diff: TypeScript types for diff Configuration removed: - debug:textile script from package.json - textile-partials filesystem plugin from gatsby-config.ts - textile-nanoc-compatible filesystem plugin from gatsby-config.ts The repository no longer has any textile-related dependencies. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- gatsby-config.ts | 16 ---------------- package.json | 6 ------ yarn.lock | 40 ++-------------------------------------- 3 files changed, 2 insertions(+), 60 deletions(-) diff --git a/gatsby-config.ts b/gatsby-config.ts index f799f167e1..603615e721 100644 --- a/gatsby-config.ts +++ b/gatsby-config.ts @@ -121,22 +121,6 @@ export const plugins = [ __key: 'images', }, // Data - { - resolve: 'gatsby-source-filesystem', - options: { - name: 'textile-partials', - path: './content/partials', - }, - __key: 'textile-partials', - }, - { - resolve: 'gatsby-source-filesystem', - options: { - name: 'textile-nanoc-compatible', - path: './content', - }, - __key: 'textile-nanoc-compatible', - }, { resolve: 'gatsby-source-filesystem', options: { diff --git a/package.json b/package.json index 81be760a99..19aab1394d 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,6 @@ "build": "yarn clean && gatsby build --prefix-paths", "build:cli": "tsc -p .", "build:compress": "tsc data/onPostBuild/compressAssets.ts --outDir data/onPostBuild --target es2020 --module commonjs --esModuleInterop --allowSyntheticDefaultImports", - "debug:textile": "yarn build:cli && node ./dist/read-textile.js", "serve": "gatsby serve --prefix-paths", "clean": "gatsby clean", "rebuild": "gatsby clean && gatsby build --prefix-paths && gatsby serve --prefix-paths", @@ -55,7 +54,6 @@ "@types/cheerio": "^0.22.31", "@types/prop-types": "^15.7.4", "cheerio": "^1.0.0-rc.10", - "diff": "^5.1.0", "dompurify": "^3.2.4", "fast-glob": "^3.3.3", "front-matter": "^4.0.2", @@ -94,8 +92,6 @@ "react-medium-image-zoom": "^5.1.2", "react-select": "^5.7.0", "remark-gfm": "^1.0.0", - "textile-js": "^2.1.1", - "turndown": "^7.1.1", "typescript": "^4.6.3", "use-keyboard-shortcut": "^1.1.6", "util": "^0.12.4", @@ -109,7 +105,6 @@ "@testing-library/jest-dom": "^5.16.5", "@testing-library/react": "^13.4.0", "@testing-library/user-event": "^14.4.3", - "@types/diff": "^5.0.2", "@types/dompurify": "^2.4.0", "@types/jest": "^29.5.7", "@types/jest-axe": "^3.5.5", @@ -118,7 +113,6 @@ "@types/lodash.throttle": "^4.1.7", "@types/react-helmet": "^6.1.6", "@types/react-test-renderer": "^18.0.0", - "@types/turndown": "^5.0.1", "@typescript-eslint/eslint-plugin": "^5.46.1", "@typescript-eslint/parser": "^7.1.1", "autoprefixer": "^10.4.13", diff --git a/yarn.lock b/yarn.lock index 54ba4b9fed..264db4a2d2 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4227,11 +4227,6 @@ dependencies: "@types/ms" "*" -"@types/diff@^5.0.2": - version "5.0.9" - resolved "https://registry.npmjs.org/@types/diff/-/diff-5.0.9.tgz" - integrity sha512-RWVEhh/zGXpAVF/ZChwNnv7r4rvqzJ7lYNSmZSVTxjV0PBLf6Qu7RNg+SUtkpzxmiNkjCx0Xn2tPp7FIkshJwQ== - "@types/dompurify@^2.4.0": version "2.4.0" resolved "https://registry.npmjs.org/@types/dompurify/-/dompurify-2.4.0.tgz" @@ -4556,11 +4551,6 @@ resolved "https://registry.npmjs.org/@types/trusted-types/-/trusted-types-2.0.7.tgz" integrity sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw== -"@types/turndown@^5.0.1": - version "5.0.4" - resolved "https://registry.npmjs.org/@types/turndown/-/turndown-5.0.4.tgz" - integrity sha512-28GI33lCCkU4SGH1GvjDhFgOVr+Tym4PXGBIU1buJUa6xQolniPArtUT+kv42RR2N9MsMLInkr904Aq+ESHBJg== - "@types/unist@^2", "@types/unist@^2.0.0", "@types/unist@^2.0.2", "@types/unist@^2.0.3": version "2.0.11" resolved "https://registry.yarnpkg.com/@types/unist/-/unist-2.0.11.tgz#11af57b127e32487774841f7a4e54eab166d03c4" @@ -7043,7 +7033,7 @@ diff-sequences@^29.6.3: resolved "https://registry.npmjs.org/diff-sequences/-/diff-sequences-29.6.3.tgz" integrity sha512-EjePK1srD3P08o2j4f0ExnylqRs5B9tJjcp9t1krH2qRi8CCdsYfwe9JgSLurFBWwq4uOlipzfk5fHNvwFKr8Q== -diff@^5.0.0, diff@^5.1.0: +diff@^5.0.0: version "5.2.0" resolved "https://registry.npmjs.org/diff/-/diff-5.2.0.tgz" integrity sha512-uIFDxqpRZGZ6ThOk84hEfqWoHx2devRFvpTZcTHur85vImfaxUbTW9Ryh4CpCuDnToOP1CEtXKIgytHBPVff5A== @@ -7143,11 +7133,6 @@ domhandler@^5.0.2, domhandler@^5.0.3: dependencies: domelementtype "^2.3.0" -domino@^2.1.6: - version "2.1.6" - resolved "https://registry.npmjs.org/domino/-/domino-2.1.6.tgz" - integrity sha512-3VdM/SXBZX2omc9JF9nOPCtDaYQ67BGp5CoLpIQlO2KCAPETs8TcDHacF26jXadGbvUteZzRTeos2fhID5+ucQ== - dompurify@^3.2.4: version "3.2.4" resolved "https://registry.npmjs.org/dompurify/-/dompurify-3.2.4.tgz" @@ -15319,16 +15304,7 @@ string-similarity@^1.2.2: lodash.map "^4.6.0" lodash.maxby "^4.6.0" -"string-width-cjs@npm:string-width@^4.2.0": - version "4.2.3" - resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010" - integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g== - dependencies: - emoji-regex "^8.0.0" - is-fullwidth-code-point "^3.0.0" - strip-ansi "^6.0.1" - -string-width@^4.0.0, string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.2, string-width@^4.2.3: +"string-width-cjs@npm:string-width@^4.2.0", string-width@^4.0.0, string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.2, string-width@^4.2.3: version "4.2.3" resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010" integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g== @@ -15792,11 +15768,6 @@ text-table@^0.2.0: resolved "https://registry.yarnpkg.com/text-table/-/text-table-0.2.0.tgz#7f5ee823ae805207c00af2df4a84ec3fcfa570b4" integrity sha512-N+8UisAXDGk8PFXP4HAzVR9nbfmVJ3zYLAWiTIoqC5v5isinhr+r5uaO8+7r3BMfuNIufIsA7RdpVgacC2cSpw== -textile-js@^2.1.1: - version "2.1.1" - resolved "https://registry.npmjs.org/textile-js/-/textile-js-2.1.1.tgz" - integrity sha512-6yP8bPtL364lb/Pu9IQh/pu9aFXQN2VSUQrzVtOrjQs0pSc+jX0iczNPcMn5+MNvmoP3piCPxFb0hPBS7DmfFg== - thenify-all@^1.0.0: version "1.6.0" resolved "https://registry.npmjs.org/thenify-all/-/thenify-all-1.6.0.tgz" @@ -15981,13 +15952,6 @@ tunnel-agent@^0.6.0: dependencies: safe-buffer "^5.0.1" -turndown@^7.1.1: - version "7.1.2" - resolved "https://registry.npmjs.org/turndown/-/turndown-7.1.2.tgz" - integrity sha512-ntI9R7fcUKjqBP6QU8rBK2Ehyt8LAzt3UBT9JR9tgo6GtuKvyUzpayWmeMKJw1DPdXzktvtIT8m2mVXz+bL/Qg== - dependencies: - domino "^2.1.6" - type-check@^0.4.0, type-check@~0.4.0: version "0.4.0" resolved "https://registry.yarnpkg.com/type-check/-/type-check-0.4.0.tgz#07b8203bfa7056c0657050e3ccd2c37730bab8f1" From 01773ed75b7f0b91e7c6707443f87d8e13a387e7 Mon Sep 17 00:00:00 2001 From: Kenneth Kalmer Date: Wed, 26 Nov 2025 21:55:51 +0000 Subject: [PATCH 5/6] Update documentation to reflect textile removal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update references in documentation and style guide to remove mentions of textile format now that it is no longer supported. Changes: - Update CONTRIBUTING.md to remove textile references - Fix prettier formatting in src/pages/docs/404.js - Update writing-style-guide.md to remove textile mention 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CONTRIBUTING.md | 26 ++++++++++++-------------- src/pages/docs/404.js | 15 ++------------- writing-style-guide.md | 2 +- 3 files changed, 15 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 804bed99e3..f9c6078d4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contribution guide -This guide covers how to contribute to the Ably docs repository. From general pull request processes, to how to update and use each textile component. +This guide covers how to contribute to the Ably docs repository, including general pull request processes and content formatting. ## Pull request process @@ -35,12 +35,12 @@ There are two main locations that contributors need to work with to varying exte | Folder | Contains | | ------ | -------- | -| content | All content pages written in textile. | -| src | Images, navigation and language version and management. | +| how-tos | Tutorial content in MDX format. | +| src | Images, navigation, and language version management. | -## Textile format +## Content format -The following sections discuss how to write and implement each component using textile. +Documentation pages use MDX format for content. The following sections discuss common formatting patterns. ### Metadata @@ -73,19 +73,17 @@ An example heading (with a custom anchor link) is: `h2(#subscribe). Subscribe to ### Links -Links in textile are written in quotation marks. Link text can also be [code styled](#in-line-code). +Use standard Markdown link syntax: `[link text](url)`. #### Internal links -To link to another heading on the same page use the anchor link: `"channel state changes":#listen-for-state`. +To link to another docs page use: `[messages](/docs/channels/message)`. -To link to another docs page use: `"messages":/docs/channels/message`. - -You may also use in-line code to style link text: `"@get()@":/docs/api/realtime-sdk/channels#get method` +To link to a heading on the same page: `[channel state changes](#listen-for-state)`. #### External links -To link externally, or outside of the docs repository, use a fully qualified link: `"Ably dashboard":https://ably.com/dashboard`. +Use fully qualified URLs: `[Ably dashboard](https://ably.com/dashboard)`. > Note: for dashboard links you can use `/any/` as the account ID to link directly to a specific page. For example: `https://ably.com/accounts/any/edit` for the account settings page. @@ -164,7 +162,7 @@ To make a cell span two columns: ### Admonitions -There are three types of admonition that can be used; `note`, `important` and `further-reading`. Update the value of `data-type` to switch between them. Admonitions are written using the HTML `