coda-js
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.1 • Public • Published

    Coda - Node API

    An eloquent Node API for interacting with your Coda Docs. This API utilizes the Coda REST API.

    npm npm type definitions npm bundle size


    Features

    • list or get specific Folder, Section, Doc, Table, Column, Row, and Control information
    • query, insert, update, or delete table data
    • more formatting options than Coda's REST API for inserting or retrieving row values
    • an eloquent API (see examples)
    • handle Coda error types

    Installation

    # yarn
    $ yarn add coda-js
    
    # npm
    $ npm install --save coda-js

    Usage

    This API uses the same method names as found in the Coda Docs. Review them for additional methods. Note that using item IDs is best (doesn't change), but each parameter that accepts an ID also accepts the name for convenience. All methods can be used from the base instance or from their respective parent. For example:

    // uses two requests, but makes sense when you don't know all information ahead of time
    const doc = await coda.getDoc('O7d9JvX0GY');
    const table = await doc.getTable('grid-_14oaR8gdM');

    could be consolidated into:

    // uses only one request, which is best when you already know the exact IDs to get the item(s) directly
    await coda.getTable('O7d9JvX0GY', 'grid-_14oaR8gdM');

    Notice

    Be aware that inserting, updating, and deleting methods are not synchronous. They return true if the operation successfully added the request to Coda's API queue. It does not directly mean that the operation was successful or that it is complete. As of v1 of the Coda API, there is a way to check if a mutation has finished. See the section on Checking Request Status to learn how to detect when an operation is completed.

    Token

    Generate your token in your Coda profile settings. Notice: Everyone with this token has full access to all your docs! It is recommended to not use this client-side or anywhere your API token could be found.

    Pagination

    Coda's v1 API added a more complete pagination system. Read the docs or the Pagination section in the Migration Guide.

    TODOs

    • [ ] add formulas API

    Examples

    Please note that the examples are currently only displaying async/await usage. You may use any strategy to handle the returned promises.

    Testing Connection

    import { Coda } from 'coda-js';
    
    const coda = new Coda('**********-********-*********'); // insert your token
    
    // trick for using async in a script
    (async () => {
      const whoAmI = await coda.whoAmI();
      console.log(whoAmI);
    })().catch((error) => console.log(error));

    Retrieving Data (List/Get)

    const docs = await coda.listDocs();
    console.log(docs);
    
    const firstDoc = docs[0];
    const firstDocTables = await firstDoc.listTables();
    console.log(firstDocTables);
    
    const columns = await firstDocTables[0].listColumns();
    console.log(columns.map((column) => column.name)); // list column names
    
    const table = docs.getTable('grid-**********'); // insert/inject table name or ID here
    const rows = await table.listRows({
      useColumnNames: true, // param to display column names rather than key
    });
    const firstRow = rows[0];
    console.log(firstRow.values); // column/value pairs
    console.log(firstRow.listValues()); // each column is object with column and value properties
    
    const tableType = table.tableType;
    const parentTable = tableType === 'view' ? return table.parentTable : table; // if the table is a view, we can access its parent Table
    console.log(parentTable.id);
    
    const controls = await coda.listControls('some-doc-ID');
    // or
    const controls = await firstDoc.listControls();

    Inserting

    Inserting also has a second parameter of keyColumns that allows for an "upsert". See Coda documentation for details.

    // inserting using object
    await table.insertRows([
      {
        Name: 'Jacob',
        Action: 'Take out the trash',
        Completed: true,
      },
    ]);
    
    // inserting via column objects
    await table.insertRows([
      [
        { column: 'Name', value: 'Alexis' },
        { column: 'Action', value: 'Do the dishes' },
      ],
      [
        { column: 'Name', value: 'Parker' },
        { column: 'Action', value: 'Make dinner' },
        { column: 'Completed', value: true },
      ],
    ]);

    Updating

    // updating (using column name instead of ID)
    await table.updateRow('i-cpDDo9hAEU', {
      Completed: false,
    });
    
    // updating via column objects
    await table.updateRow('i-dF2-OoiiUi', [{ column: 'Action', value: 'Make the bed' }]);
    
    // updating off of an already fetched row
    await row2.update({
      'ai-dRD9afcc8': 'To the moon, Alice!',
    });

    Deleting

    // delete row directly
    const row4 = await table.getRow('i-Ef2-OoZxIi');
    await row4.delete();
    
    // delete row from table
    await table.deleteRow('i-cpDDoshUEU');
    
    // deleting multiple rows from table
    await table.deleteRows(['i-cpDDoshUEU', 'i-jj81vtosO1']);

    Checking Request Status

    Inserting, updating, and deleting in Coda is not always processed immediately. Check the mutation status if you need to make sure it was completed:

    // for an update
    const request = await todo.update({
      Completed: !completed,
    });
    const requestCompleted = await request.isCompleted();
    
    // for a delete
    const request = await table.deleteRow('i-cpDDoshUEU');
    if (await request.isCompleted()) {
      // ... do something
    }
    
    // a little more manually
    const requestCompleted = await coda.mutationStatus('some-request-id');

    Error Handling

    Error types:

    • BadRequestError (400)
    • UnauthorizedError (401)
    • ForbiddenError (403)
    • NotFoundError (404)
    • GoneError (410)
    • TooManyRequestsError (429)
    import { Coda, UnauthorizedError, NotFoundError } from '../index';
    const coda = new Coda(process.env.TOKEN);
    
    // doesn't have access to view docs
    try {
      await coda.listDocs();
    } catch (error) {
      // error is instance of UnauthorizedError
      // can also determine based on (error.name === 'UnauthorizedError')
    }
    
    // fails to find a doc with a bad ID
    try {
      const BAD_DOC_ID = 'd-ckjd1013kkk';
      await coda.listTables(BAD_DOC_ID);
    } catch (error) {
      // error is instance of NotFoundError
      // can also determine based on (error.name === 'NotFoundError')
    }

    Install

    npm i coda-js

    DownloadsWeekly Downloads

    276

    Version

    4.0.1

    License

    ISC

    Unpacked Size

    2.1 MB

    Total Files

    280

    Last publish

    Collaborators

    • avatar