ec.fdk

Featherweight Development Kit for entrecode APIs.

ec.fdk docs

Install

npm i ec.fdk

Getting Started

There are 2 ways to use ec.fdk:

• method chaining
• act

Method Chaining

Start by calling fdk with your environment (stage | live), then method chain your way to success:

import { fdk } from "ec.fdk";

fdk("stage") // choose stage environment
  .dm("83cc6374") // select datamanager via short id
  .model("muffin") // select model muffin
  .entryList() // load entry list
  .then((list) => {
    console.log(list);
  });

See all functions in the Fdk reference.

act

The act function converts a single object param into a fetch request:

const muffins = await act({
  action: "entryList",
  env: "stage",
  dmShortID: "83cc6374",
  model: "muffin",
});

More in the act reference.

Using act with swr / react-query

The act function is good to be used with swr or react-query:

import { act } from "ec.fdk";
import useSWR from "swr";

export function useFdk(config) {
  const key = config ? JSON.stringify(config) : null;
  return useSWR([key], () => act(config));
}

Then use the hook:

const config = {
  env: "stage",
  dmShortID: "83cc6374",
};

function App() {
  const { data: entryList } = useFdk({
    ...config,
    action: "entryList",
    model: "muffin",
  });
  /* more stuff */
}

migration from ec.sdk

ec.fdk won't change / decorate data returned from ec APIs. For example, an entry returned from the datamanager will be returned as is. Advantages:

• The network tab shows what goes into the frontend
• Resources have the same shape everywhere
• Resources are serializable

Entry save

Instead of mutating an EntryResource and calling .save(), we now pass the new value directly:

// this does not exist anymore:
await entry.save(); // <- DONT
// use this to update an entry:
await editEntryObject(entry, value); // <- DO
// alternatively:
await fdk.env(env).dm(dmShortID).model(model).updateEntry(entryID, value);
// or:
await act({ action: "editEntry", env, dmShortID, model, entryID, value });

Entry delete

Similar to save:

// this does not exist anymore:
await entry.del(); // <- DONT
// use this to delete an entry:
await deleteEntryObject(entry); // <- DO
// alternatively:
await fdk.dm("shortID").model("model").deleteEntry("entryID");
// or:
await act({ action: "deleteEntry", env, dmShortID, model, entryID });

Entry Asset Fields

In ec.fdk, entry asset fields are plain ids:

// assuming "photo" is an asset field:
entry.photo; // <-- this used to be an AssetResource. Now it's a plain id string.
// use this to get the embedded AssetResource:
getEntryAsset("photo", entry); // (no request goes out)

Entry Date Fields

// assuming "lastSeen" is a datetime field:
entry.lastSeen; // <-- this used to be an instance of Date. Now it's a date ISO string
// use this to get a Date instance:
new Date(entry.lastSeen);

Entry List

// ec.sdk
const api = new PublicAPI(shortID, env, true);
const entryList = await api.entryList(model);
const items = entryList.getAllItems();
const first = entryList.getFirstItem();
// ec.fdk
const api = fdk(env).dm(shortID);
const entryList = await api.entryList(model);
const items = entryList.items; // <------- change
const first = entryList.items[0]; // <------- change
// or in one line:
const entryList = await fdk(env).dm(shortID).entryList(model);

Entry List Filter Options

By default, the second param of ec.fdk entryList will just convert the object to url params:

const entryList = await fdk("stage")
  .dm("83cc6374")
  .entryList({ createdTo: "2021-01-18T09:13:47.605Z" });
/* 
https://datamanager.cachena.entrecode.de/api/83cc6374/muffin?
_list=true&
createdTo=2021-01-18T09:13:47.605Z&
page=1&
size=50
*/

Read more in the entrecode filtering doc

There is some syntax sugar you can use to get the same behavior as ec.sdk filterOptions:

const entryList = await fdk("stage")
  .dm("83cc6374")
  .entryList(filterOptions({ created: { to: "2021-01-18T09:13:47.605Z" } }));

Asset List

// ec.sdk
await api.dmAssetList(group, { assetID: { any: value } });
// ec.fdk
const options = sdkOptions({ assetID: { any: value } } as any);
const assets = await api.assetGroup(group).assetList(options);

Load Asset

// ec.sdk
api.dmAsset(group, img);
// ec.fdk
api.assetGroup(group).getAsset(img);

Publish

0. cd packages/ec.fdk
1. bump version in packages/ec.fdk/package.json
2. run npm run docs to regenerate docs folder
3. commit + push
4. run pnpm publish