npm package: @growthcurve/baltu-js
Description: Baltu SDK for vanilla JavaScript — deliver in-app tooltips, modals, banners, tours and checklists with any framework
Latest version: 1.0.1

# @baltu/js

The official vanilla JavaScript SDK for [Baltu](https://usebaltu.com) — the open-source product adoption platform.

Works with any framework: Vue, Svelte, Angular, or plain HTML. For React, use [`@baltu/react`](https://www.npmjs.com/package/@baltu/react).

## Installation

```bash
npm install @baltu/js
```

Or via CDN:

```html
<script src="https://cdn.usebaltu.com/sdk/v1/baltu.min.js"></script>
```

## Quick Start

```typescript
import { init } from "@baltu/js";

const baltu = init({
  organizationId: "your-org-id",
  apiKey: "your-api-key",
  userId: currentUser.id,
  userProperties: {
    name: currentUser.name,
    email: currentUser.email,
    plan: currentUser.plan,
  },
});
```

## Framework Examples

### Vue.js

```typescript
// main.ts
import { createApp } from "vue";
import { init } from "@baltu/js";
import App from "./App.vue";

const app = createApp(App);

init({
  organizationId: "your-org-id",
  apiKey: "your-api-key",
  userId: currentUser.id,
  userProperties: { plan: currentUser.plan },
});

app.mount("#app");
```

### Svelte

```svelte
<!-- +layout.svelte -->
<script>
  import { init } from "@baltu/js";
  import { onMount } from "svelte";

  onMount(() => {
    init({
      organizationId: "your-org-id",
      apiKey: "your-api-key",
      userId: currentUser.id,
    });
  });
</script>

<slot />
```

### Angular

```typescript
// app.component.ts
import { Component, OnInit } from "@angular/core";
import { init } from "@baltu/js";

@Component({ selector: "app-root", templateUrl: "./app.component.html" })
export class AppComponent implements OnInit {
  ngOnInit() {
    init({
      organizationId: "your-org-id",
      apiKey: "your-api-key",
      userId: this.auth.currentUser.id,
    });
  }
}
```

## API

### `init(config)` → `BaltuInstance`

Initialize the SDK. Returns an instance with these methods:

| Method | Description |
|--------|-------------|
| `identify(userId, properties)` | Set or update the current user |
| `refresh()` | Reload blocks from server |
| `getBlocks()` | Get currently visible blocks |
| `on(event, callback)` | Subscribe to SDK events |
| `off(event, callback)` | Unsubscribe from events |
| `action(blockId, key)` | Trigger a block action |
| `dismiss(blockId)` | Dismiss a block |
| `startWorkflow(id)` | Start a specific workflow |
| `resetWorkflow(id)` | Reset workflow progress |
| `destroy()` | Clean up and remove all UI |

### Events

```typescript
baltu.on("block-activated", (block) => {
  console.log("Showing:", block.id);
});

baltu.on("workflow-complete", (workflowId) => {
  console.log("Completed:", workflowId);
});
```

## Components

The SDK renders 8 component types with a built-in DOM renderer:

- **Modal** — centered overlay dialogs
- **Banner** — top/bottom notification bars
- **Tooltip** — positioned next to target elements
- **Card** — floating info cards
- **Hint** — pulsing indicators on elements
- **Sidebar** — slide-in panels
- **Checklist** — task completion lists
- **Floating Checklist** — compact progress widget

## SPA Support

The SDK automatically detects URL changes (polling every 250ms) and re-evaluates page targeting rules — no additional configuration needed for React Router, Vue Router, or any SPA routing library.

## License

MIT