npm package: @notebits/sdk
Description: (This README has been generated by AI with a bunch of other random notes and so needs some reworking to really useful, but I wanted to at least capture the broad strokes of the SDK setup for future reference for myself and to make it easy for other develo
Latest version: 0.0.1

# Notebits SDK

(This README has been generated by AI with a bunch of other random notes and so
needs some reworking to really useful, but I wanted to at least capture the
broad strokes of the SDK setup for future reference for myself and to make it
easy for other developers to use the SDK even in its early rough form - esp.
for Maptio developers - I want the setup to pass the bus test.)

This repository contains the Notebits SDK, used by both the Notebits and Maptio
projects. The SDK is maintained as a library within the `notebits` Nx monorepo
and can be included in other projects (e.g. Maptio) as a git submodule.

# Developing the notebits SDK for Maptio

# Pushing changes from notebits to the SDK repository

Run the following command from the root of the notebits repository, assuming
you have a bare repo for notebits-sdk at `../notebits-sdk`:

```
git subtree push --prefix=libs/sdk ../notebits-sdk.git main
```

# Pulling code changes to the notebits SDK into another project

Go to the other project (e.g. Maptio) and run:

```
git submodule update --remote libs/notebits-sdk
```

# When Maptio needs changes...

How it would work (technically): Modify SDK in Maptio: Navigate to the
submodule directory within Maptio: cd
/Users/romek/Spaces/Projects/Maptio/Code/maptio/libs/notebits-sdk This
directory is itself a Git repository (a clone of your notebits-sdk.git). You
can make changes, commit them, and even create branches here. Example: Apply to
README.md Run " Push Changes from Maptio's Submodule to the Shared SDK Repo:
From within Maptio/libs/notebits-sdk, you can push to the notebits-sdk.git
repository: Apply to README.md Run

(This assumes origin for the submodule points to
/Users/romek/Spaces/Projects/notebits/9_Code/notebits-sdk.git and you're on the
main branch within the submodule). Now, your notebits-sdk.git (the local bare
repo) has these new changes. Fetching Changes into notebits Monorepo
(notebits/libs/sdk): This is where it gets tricky with your git subtree setup.
git subtree is primarily designed for pushing out of a monorepo subdirectory.
Pulling changes into that subdirectory from an external repository that has
diverged is more complex. Option A (Manual Sync - Simpler, More Control): Clone
the updated notebits-sdk.git to a temporary location: Apply to README.md Run
sync Navigate to your notebits monorepo: cd
/Users/romek/Spaces/Projects/notebits/9_Code/notebits Manually copy the changed
files from /tmp/temp-sdk-sync over the files in libs/sdk. Be careful here to
handle merges or conflicts if any. Commit these changes in the notebits
monorepo: Apply to README.md Run " Option B (git subtree pull - More Automated,
Can Be Complex): This is generally not recommended if the history in
notebits-sdk.git has been contributed from multiple places without careful
coordination, as subtree pull can sometimes have unexpected merge outcomes. The
command would look something like this from the root of the notebits repo: git
subtree pull --prefix=libs/sdk
/Users/romek/Spaces/Projects/notebits/9_Code/notebits-sdk.git main --squash
(Using --squash might simplify the history brought into notebits). You'd need
to resolve any conflicts.

## Recommended Workflow (Maintain Source of Truth in notebits):

It's generally best to stick to the workflow where all SDK changes originate in
notebits/libs/sdk:

If you're working in Maptio and identify a needed SDK change:

- Switch to your notebits monorepo.
- Make the change in notebits/libs/sdk.
- Use npm link (as described in the README) to test these live changes in
  Maptio.
- Once satisfied, commit the change in notebits.
- Run git subtree push --prefix=libs/sdk ../notebits-sdk.git main from the
  notebits root.
- In Maptio, run git submodule update --remote libs/notebits-sdk and commit the
  updated submodule pointer.

This maintains a clear, unidirectional flow for the SDK's authoritative code
and aligns with the setup we've created.

## For Developers Consuming the SDK (e.g. in the Maptio project)

If you are primarily working on e.g. Maptio and consuming the SDK (i.e., you do
not have or need access to the `notebits` monorepo):

### Initial Setup

When you first clone the Maptio repository, or if you've pulled changes that
introduced this submodule, the `libs/notebits-sdk` directory might be empty. To
initialize and fetch the SDK code, run the following command from the root of
the Maptio repository:

```bash
git submodule update --init --recursive
```

This command will populate this `libs/notebits-sdk` directory with the correct
version of the SDK as specified by the Maptio project.

### Updating the SDK to a Newer Version

When a new version of the SDK is ready and the Maptio project has been updated
to point to it, simply pulling the latest changes for the Maptio main branch
should update the submodule reference. After pulling, if the submodule content
doesn't automatically update, or to ensure you have the latest referenced
version:

```bash
git submodule update --recursive
```

If project maintainers announce that the submodule itself needs to point to a
newer commit not yet referenced by Maptio's main branch (less common), you
might be instructed to run:

```bash
git submodule update --remote libs/notebits-sdk
```

Followed by committing the change to the submodule pointer in Maptio.
Typically, you'll get submodule updates via a normal `git pull` from Maptio's
main branch.

## For SDK Developers (Modifying the SDK - Requires `notebits` Repo Access)

If you need to make changes to the Notebits SDK itself, the source of truth for
the SDK resides in the `notebits` monorepo (typically at `libs/sdk` within that
project).

### Local Development & Rapid Iteration (SDK Changes Tested in Maptio)

For a faster feedback loop when actively developing the SDK and testing changes
in Maptio simultaneously:

1.  **Navigate to the `notebits` Monorepo:** Open a terminal in your local
    clone of the `notebits` monorepo (e.g.,
    `/Users/romek/Spaces/Projects/notebits/9_Code/notebits`).

2.  **Make SDK Changes:** Modify the SDK code located at `libs/sdk` within the
    `notebits` monorepo.

3.  **Build the SDK (in `notebits`):** Run the SDK's build command from the
    root of the `notebits` monorepo.

    ```bash
    # In the notebits monorepo root
    nx build sdk
    ```

4.  **Link the Local SDK Build (in `notebits`):** Navigate to the build output
    directory of the SDK in `notebits` (usually `dist/libs/sdk`):

    ```bash
    # In the notebits monorepo root
    cd dist/libs/sdk
    npm link
    cd ../../.. # Navigate back to notebits root
    ```

    (If your SDK is scoped, e.g., `@your-org/sdk`, `npm link` will register it
    under that name. Note this name for the next step.)

5.  **Link in `Maptio`:** Navigate to your `Maptio` monorepo root
    (`/Users/romek/Spaces/Projects/Maptio/Code/maptio`):

    ```bash
    # In the Maptio monorepo root
    npm link <sdk-package-name>
    ```

    Replace `<sdk-package-name>` with the actual name of your SDK package as
    defined in its `package.json` (e.g., `notebits-sdk` or `@notebits/sdk`).
    You can find this name in the `package.json` file of the
    `notebits/libs/sdk` library.

    Now, Maptio will use your locally built SDK from `notebits`. Changes you
    make in `notebits` (followed by a rebuild and, if necessary, restarting
    Maptio's dev server) will be reflected when you run/build Maptio.

### Finalizing SDK Changes (Publishing to Maptio)

Once you're satisfied with your SDK modifications and they've been tested:

1.  **Commit SDK Changes in `notebits`:** In the `notebits` monorepo, commit
    your changes to the SDK.

2.  **Push SDK to Shared Repository (from `notebits`):** From the root of the
    `notebits` monorepo, push the SDK changes to the shared SDK repository:

    ```bash
    # In the notebits monorepo root
    git subtree push --prefix=libs/sdk /Users/romek/Spaces/Projects/notebits/9_Code/notebits-sdk.git main
    ```

    _(Note: If the shared SDK repository eventually moves to a remote like
    GitHub, this URL will need to be updated.)_

3.  **Unlink in `Maptio` (Recommended):** To ensure Maptio reverts to using the
    versioned submodule from the shared repository rather than the locally
    linked version:

    ```bash
    # In the Maptio monorepo root
    npm unlink <sdk-package-name>
    # It's good practice to run `npm install` or ensure your
    # package-lock.json/yarn.lock is consistent.
    npm install
    ```

4.  **Update Submodule in `Maptio`:** In the `Maptio` monorepo root, pull the
    latest changes for the submodule:

    ```bash
    # In the Maptio monorepo root
    git submodule update --remote libs/notebits-sdk
    ```

    This fetches the latest from the shared SDK repo (that you just pushed to)
    into your `Maptio/libs/notebits-sdk` directory and updates the submodule's
    checked-out commit.

5.  **Commit Submodule Update in `Maptio`:** The previous step changes which
    commit the `libs/notebits-sdk` submodule points to. Stage this change and
    commit it to the Maptio repository:
    ```bash
    # In the Maptio monorepo root
    git add libs/notebits-sdk
    git commit -m "Update notebits-sdk to latest version"
    git push # Push Maptio changes to its remote repository
    ```

---

This setup allows Maptio to use a version-controlled, stable version of the SDK
while enabling rapid local development and testing for those working on the SDK
itself. Remember to replace `<sdk-package-name>` with the actual package name
of your SDK.