Appspace
@dougschaefer/appspacev2026.05.27.2
01README
Appspace Cloud v3 API administration toolkit — devices, reservations, users, visitors, and the custom card development lifecycle (scaffold, pull existing, validate, package, register instances). Walk-in workflows fire DropIn invitations through Appspace's native notification routing (Teams Passport, in-app push, Concierge) with no external webhook required.
02Release Notes
Hardened the card packager to exclude swamp internals (.swamp/, *.db) at any depth and added a verifyPackage gate — fixes Appspace rejecting card uploads with a 500 (invalid .db file type).
03Models
@dougschaefer/appspace-cardv1.0.0appspace/card.ts
fn scaffold(path: string, id: string, name: string, developer: string)
Create a new Appspace card project at the given path with manifest.json, schema.json, model.json, index.html, and a placeholder thumbnail. Defaults to a plain HTML/JS template (zero build step) — extend with React/Angular as needed.
| Argument | Type | Description |
|---|---|---|
| path | string | Destination directory (created if missing). Should be empty. |
| id | string | Reverse-DNS card identifier (e.g., 'com.example.lobby.welcome') |
| name | string | Human-readable card name |
| developer | string | Developer/author name for the manifest (your company or org) |
fn validate(path: string)
Validate a card project's Big Three (manifest.json, schema.json, model.json) for required fields and consistency. Returns warnings without modifying files.
| Argument | Type | Description |
|---|---|---|
| path | string | Path to card project directory |
fn build(path: string, command: string, args: array)
Run a build command in the card project directory (e.g., 'npm run build'). Skip for plain-HTML cards that need no build.
| Argument | Type | Description |
|---|---|---|
| path | string | Path to card project directory |
| command | string | Build executable |
| args | array | Build command arguments |
fn package(sourceDir: string, outputZip: string, excludeGlobs: array)
Package a card project into a .zip ready for upload to Appspace. Handles the 'zip contents not folder' gotcha by archiving entries with paths relative to the source dir. Run validate first.
| Argument | Type | Description |
|---|---|---|
| sourceDir | string | Directory whose contents to package (typically build/ or the project root for plain cards) |
| outputZip | string | Path where the .zip should be written (e.g., 'dist/my-card.zip') |
| excludeGlobs | array | Entries to skip at ANY depth (matched against the entry name). Appspace rejects .db files, so swamp's nested .swamp/ catalogs must never be bundled. |
fn verifyPackage(zipPath: string)
Gate a built card .zip before upload: fail if it contains swamp/vcs/OS internals or DB-type files (Appspace rejects .db with a 500), or is missing the files the manifest references (Schema/Model/Startup/Thumbnail) at the zip root. Throws on any violation so a build workflow stops before a bad upload. Run after `package`.
| Argument | Type | Description |
|---|---|---|
| zipPath | string | Path to the built card .zip to verify |
fn listTemplateTypes()
List all card template types installed on the Appspace tenant. Use the returned 'id' as cardTemplateTypeId when creating new template instances.
fn listTemplates(maxItems?: number)
List configured card template instances in the Appspace library.
| Argument | Type | Description |
|---|---|---|
| maxItems? | number |
fn getTemplate(id: string)
Get a single card template by ID.
| Argument | Type | Description |
|---|---|---|
| id | string | Card template ID |
fn createTemplate(cardTemplateTypeId: string, name: string, model?: record, schema?: record, permissions?: array, theme?: record)
Create a new configured card template instance from a registered template type. The 'model' and 'schema' fields override the template type's defaults for this instance.
| Argument | Type | Description |
|---|---|---|
| cardTemplateTypeId | string | ID of the template type to instantiate (from listTemplateTypes) |
| name | string | Display name for the instance |
| model? | record | Per-instance model.json overrides |
| schema? | record | Per-instance schema.json overrides |
| permissions? | array | |
| theme? | record |
fn pullCard(templateId: string, destDir: string, includeAssets: boolean)
Download a card's source files from its templateUrl on the Appspace tenant. Fetches manifest/schema/model/index.html plus every script and stylesheet referenced from index.html (preserving the relative directory structure). NOTE: dynamically-loaded files (translations under console/lang/*, fonts/, console/react/*, SVG assets) are not statically referenced so they won't be picked up — if pulling a customer-customized card to re-base, the bundle may be stripped. Warns when fewer than 50 files are
| Argument | Type | Description |
|---|---|---|
| templateId | string | Card template instance ID (UUID). Find via listTemplates. |
| destDir | string | Destination directory. Created if missing; existing files are overwritten. |
| includeAssets | boolean | When true (default), follow JS/CSS references from index.html and download those too. When false, only fetches root files (manifest, schema, model, index.html, thumbnail.svg). |
fn inspectChannel(channelId: string, includeContentModels: boolean)
Probe an Appspace channel and return its metadata, every playlist item, and (when the item is a card) the deployed model.json with the live per-instance input values. Useful for debugging why a card configured in the Appspace console isn't behaving as expected — channel-level card content has its own model.json overrides separate from the library template's defaults, and the only authoritative way to see what a kiosk is actually running with is to fetch that deployed model.
| Argument | Type | Description |
|---|---|---|
| channelId | string | Appspace channel UUID (find via the channel's URL in the console, e.g. /channels/<UUID>). |
| includeContentModels | boolean | When true (default), fetches the deployed model.json for each card item in the playlist. Set false to skip and just return playlist metadata. |
fn getContentModel(contentId: string)
Fetch the deployed model.json for an Appspace content item — the live per-instance input values, NOT the library template defaults. Looks up the content via libraries/contents to resolve its current contentURL, then fetches the matching model.json. Use this to verify what configuration a kiosk is actually running with when you only have a contentId.
| Argument | Type | Description |
|---|---|---|
| contentId | string | Appspace content UUID |
fn updateTemplate(id: string, cardTemplateTypeId?: string, name?: string, model?: record, schema?: record, theme?: record)
Update a configured card template instance (name, model overrides, schema overrides, theme).
| Argument | Type | Description |
|---|---|---|
| id | string | Card template instance ID |
| cardTemplateTypeId? | string | ID of the underlying template type. Required by the PUT endpoint (full-replace); if omitted it is recovered from the existing instance's cardTemplateType.id. |
| name? | string | |
| model? | record | |
| schema? | record | |
| theme? | record |
Resources
cardTemplateType(infinite)— Registered card template type — the developer-uploaded card 'class' that instances are created from
cardTemplate(infinite)— Configured card template instance — references a cardTemplateType and stores the per-instance schema/model overrides
cardProject(infinite)— Local card project on disk — directory containing manifest.json, schema.json, model.json, and the card's web app
cardPackage(infinite)— Built and zipped card ready to upload to Appspace
cardPackageVerification(infinite)— Upload-safety verdict for a built card .zip — confirms no swamp/vcs/OS internals or DB-type files (which Appspace rejects with a 500) and that the manifest-referenced files are present at the zip root.
cardPull(infinite)— Source files pulled from a card's templateUrl on the Appspace tenant — manifest, schema, model, index.html, and all referenced JS/CSS/asset bundles
channel(infinite)— Appspace channel — top-level container that publishes content to one or more devices. Has an associated playlist (1:1) of cards/articles.
channelPlaylistItem(infinite)— Single item (card content, article, or media) in a channel's playlist. References a contentId whose deployed model.json holds the per-instance configured input values.
contentModel(infinite)— Deployed model.json for a content item — the live per-instance input values as the kiosk runtime sees them. Distinct from the library template's model.json defaults; this captures whatever a user (or the console editor) saved on the content.
@dougschaefer/appspace-devicev2026.05.27.2appspace/device.ts
fn list(locationId?: string, groupId?: string, status?: string, maxItems?: number)
Query devices with optional filtering. Pages through results automatically.
| Argument | Type | Description |
|---|---|---|
| locationId? | string | Filter by location ID |
| groupId? | string | Filter by device group ID |
| status? | string | Filter by status (Online, Offline, etc.) |
| maxItems? | number | Maximum devices to return |
fn get(id: string)
Get details for a specific device by ID.
| Argument | Type | Description |
|---|---|---|
| id | string | Device ID (UUID) |
fn getStatuses(deviceIds?: array)
Query live status for devices (online/offline, sync state, etc.).
| Argument | Type | Description |
|---|---|---|
| deviceIds? | array | Optional list of device IDs to filter on |
fn getProperties(deviceId: string)
Get all Player Properties for a device. These are key/value pairs used to override card configuration per device (e.g., API credentials, datasourceurl).
| Argument | Type | Description |
|---|---|---|
| deviceId | string | Device ID |
fn setProperties(deviceId: string, properties: record)
Upsert one or more Player Properties on a device. Property names must be lowercase and case-sensitive.
| Argument | Type | Description |
|---|---|---|
| deviceId | string | Device ID |
| properties | record | Map of property name (lowercase) → value |
fn deleteProperties(deviceId: string, propertyNames: array)
Remove specific Player Properties from a device.
| Argument | Type | Description |
|---|---|---|
| deviceId | string | Device ID |
| propertyNames | array | Property names to delete |
fn sendCommand(deviceId: string, command: string, parameters?: record)
Send a command to a device (restart, reload, screenshot, etc.). Available commands depend on device type.
| Argument | Type | Description |
|---|---|---|
| deviceId | string | Device ID |
| command | string | Command name (e.g., 'restart', 'reload', 'screenshot') |
| parameters? | record | Optional command parameters |
fn getConfiguration(deviceId: string)
Get the runtime configuration for a device.
| Argument | Type | Description |
|---|---|---|
| deviceId | string | Device ID |
fn screenCapture(deviceId: string)
Get the latest screen capture URL for a device (only available for devices with screencapture capability).
| Argument | Type | Description |
|---|---|---|
| deviceId | string | Device ID |
fn listGroups()
List all device groups.
fn sync(deviceIds: array)
Trigger a content sync on one or more devices (push channel/playlist updates).
| Argument | Type | Description |
|---|---|---|
| deviceIds | array | Device IDs to sync |
fn listIntegrations()
List third-party device integrations configured for the account (e.g., Crestron Fusion, Cisco Webex).
fn listTaskDeployments(locationId?: string, deviceId?: string, deviceGroupId?: string)
Query task deployments (firmware updates, configuration pushes, etc.) by location, device, or group.
| Argument | Type | Description |
|---|---|---|
| locationId? | string | |
| deviceId? | string | |
| deviceGroupId? | string |
fn createTaskDeployment(taskTemplateId: string, targetType: enum, targetIds: array, scheduledAt?: string)
Deploy a task (firmware update, configuration, command) to one or more targets.
| Argument | Type | Description |
|---|---|---|
| taskTemplateId | string | Task template ID to deploy |
| targetType | enum | What to target |
| targetIds | array | IDs of targets |
| scheduledAt? | string | ISO 8601 datetime to schedule the deployment (defaults to immediate) |
fn getTaskResponses(deviceId: string, taskClass?: string)
Get task execution responses for a device (results of firmware updates, command executions, etc.).
| Argument | Type | Description |
|---|---|---|
| deviceId | string | Device ID |
| taskClass? | string | Optional task class filter |
Resources
device(infinite)— Appspace-managed display device with location, group, channel, and runtime status
deviceGroup(infinite)— Group of Appspace devices for batch operations
deviceProperties(infinite)— Player Properties for a specific device (used for per-device card overrides like API credentials)
taskDeployment(infinite)— Task deployed to a device, group, or location (firmware update, command, etc.)
@dougschaefer/appspace-reservationv2026.05.27.2appspace/reservation.ts
fn listEvents(startAt?: string, endAt?: string, resourceId?: string, maxItems?: number)
List reservation events with optional date and resource filtering. Pages automatically.
| Argument | Type | Description |
|---|---|---|
| startAt? | string | ISO 8601 — return events at or after this time |
| endAt? | string | ISO 8601 — return events at or before this time |
| resourceId? | string | Filter by resource ID (room, desk, etc.) |
| maxItems? | number |
fn getEvent(eventId: string)
Get details for a specific event.
| Argument | Type | Description |
|---|---|---|
| eventId | string |
fn cancelEvent(eventId: string, reason?: string)
Cancel an event.
| Argument | Type | Description |
|---|---|---|
| eventId | string | |
| reason? | string |
fn endEvent(eventId: string)
End an event early (releases the resource for the remaining duration).
| Argument | Type | Description |
|---|---|---|
| eventId | string |
fn extendEvent(eventId: string, endAt: string)
Extend an event's end time.
| Argument | Type | Description |
|---|---|---|
| eventId | string | |
| endAt | string | New end time (ISO 8601) |
fn releaseEvent(eventId: string)
Release resources from an event without cancelling it.
| Argument | Type | Description |
|---|---|---|
| eventId | string |
fn checkinEvent(eventId: string)
Check in to an event (confirm occupancy).
| Argument | Type | Description |
|---|---|---|
| eventId | string |
fn listReservations(startAt?: string, endAt?: string, resourceId?: string, organizer?: string, maxItems?: number)
Query reservations with optional filtering. Pages automatically.
| Argument | Type | Description |
|---|---|---|
| startAt? | string | |
| endAt? | string | |
| resourceId? | string | |
| organizer? | string | Filter by organizer email |
| maxItems? | number |
fn getReservation(reservationId: string)
Get details for a specific reservation.
| Argument | Type | Description |
|---|---|---|
| reservationId | string |
fn createReservation(title: string, startAt: string, endAt: string, resourceIds: array, organizerEmail?: string, attendees?: array, notes?: string, isAllDay?: boolean)
Create a new reservation.
| Argument | Type | Description |
|---|---|---|
| title | string | Reservation title |
| startAt | string | Start time (ISO 8601) |
| endAt | string | End time (ISO 8601) |
| resourceIds | array | Reservable resource IDs (rooms, desks, etc.) |
| organizerEmail? | string | Organizer email (defaults to token user) |
| attendees? | array | Attendee emails |
| notes? | string | |
| isAllDay? | boolean |
fn updateReservation(reservationId: string, title?: string, startAt?: string, endAt?: string, notes?: string)
Update one or more properties of an existing reservation.
| Argument | Type | Description |
|---|---|---|
| reservationId | string | |
| title? | string | |
| startAt? | string | |
| endAt? | string | |
| notes? | string |
fn deleteReservation(reservationId: string)
Delete a reservation.
| Argument | Type | Description |
|---|---|---|
| reservationId | string |
fn listReservableResources(resourceType?: string, buildingId?: string, maxItems?: number)
List resources (rooms, desks, equipment) that can be reserved.
| Argument | Type | Description |
|---|---|---|
| resourceType? | string | Filter by type (e.g., 'Room', 'Desk') |
| buildingId? | string | |
| maxItems? | number |
fn getMyEvents(startAt?: string, endAt?: string)
Get events related to the current user (the Service Account behind the token).
| Argument | Type | Description |
|---|---|---|
| startAt? | string | |
| endAt? | string |
fn checkUserAvailability(attendees: array, startAt: string, endAt: string)
Check whether one or more users are available during a given time window.
| Argument | Type | Description |
|---|---|---|
| attendees | array | List of attendee emails |
| startAt | string | Start time (ISO 8601) |
| endAt | string | End time (ISO 8601) |
fn getSchedule(resourceIds: array, startAt: string, endAt: string)
Get a schedule view across resources for a given time window.
| Argument | Type | Description |
|---|---|---|
| resourceIds | array | Resources to include |
| startAt | string | |
| endAt | string |
Resources
event(infinite)— Reservation event — a scheduled instance bound to one or more resources, possibly synced from an external calendar provider
reservation(infinite)— Reservation record — the booking abstraction that owns one or more events and tracks attendees, checkpoints, and resources
reservableResource(infinite)— Resource (room, desk, equipment) that can be reserved
@dougschaefer/appspace-userv2026.05.27.2appspace/user.ts
fn list(maxItems?: number, userType?: string)
Query users with pagination. Returns the full user directory by default; pass maxItems to cap.
| Argument | Type | Description |
|---|---|---|
| maxItems? | number | Maximum users to return |
| userType? | string | Filter by user type (e.g. 'User', 'Visitor') |
fn get(id: string)
Get a specific user by ID.
| Argument | Type | Description |
|---|---|---|
| id | string | User UUID |
fn findByEmail(email: string, exact: boolean, maxScan?: number)
Find users by email — workaround for the missing email-filter on /users. Pages through the directory and matches case-insensitively. Returns the matched user(s) as data; logs a warning if directory exceeds maxScan.
| Argument | Type | Description |
|---|---|---|
| string | Email to find (case-insensitive). Substring match by default. | |
| exact | boolean | When true, match exact email; when false, substring match. |
| maxScan? | number | Maximum directory entries to scan before giving up |
fn me()
Get the current user (the Service Account behind the API token). Useful for confirming token identity and inspecting account context.
fn listGroups(maxItems?: number)
List all user groups in the account.
| Argument | Type | Description |
|---|---|---|
| maxItems? | number |
fn getGroupMembers(groupId: string, maxItems?: number)
List members of a specific user group.
| Argument | Type | Description |
|---|---|---|
| groupId | string | User group UUID |
| maxItems? | number |
Resources
user(infinite)— Appspace user — directory record with email, location, roles, group memberships
userGroup(infinite)— Appspace user group with role assignments and network
me(1d)— Current user (the Service Account behind the API token); useful to confirm token identity
@dougschaefer/appspace-visitorv2026.05.27.2appspace/visitor.ts
fn list(maxItems?: number)
Query the visitor list with optional filtering.
| Argument | Type | Description |
|---|---|---|
| maxItems? | number |
fn get(id: string)
Get a specific visitor by ID.
| Argument | Type | Description |
|---|---|---|
| id | string | Visitor UUID |
fn create(firstName: string, lastName: string, email: string, visitorType: string, customFields: array)
Create a visitor record. Required: firstName, lastName, email, visitorType. customFields must be empty array unless the account has custom visitor fields configured. Note: bare visitor creation does NOT trigger the host-notification chain — pair with createDropInInvitation for walk-in workflows.
| Argument | Type | Description |
|---|---|---|
| firstName | string | |
| lastName | string | |
| string | ||
| visitorType | string | Visitor type label — free-form string. Defaults to 'Guest'. |
| customFields | array | Custom field values. Field IDs must be pre-configured in /visitormanagement/configurations/me/visitorfields. |
fn delete(id: string)
Delete a visitor by ID.
| Argument | Type | Description |
|---|---|---|
| id | string | Visitor UUID |
fn getConfiguration()
Get the account's Visitor Management configuration — required fields, custom field definitions, visit purposes, visitor types, retention, and the notification config block that controls Teams Passport / Appspace app push / email routing.
fn createDropInInvitation(firstName: string, lastName: string, email: string, company?: string, notes?: string, hostUserId: string, hostEmail: string, resourceId?: string, durationMinutes: number, visitorType: string, purpose: string, timezone: string)
Create a walk-in visitor + DropIn invitation in a single call. Mirrors the kiosk's `visitorsKioskCreateDropin` flow: creates the visitor record, then POSTs an invitation tied to the host. Appspace's configured Notifications fan out from there.
| Argument | Type | Description |
|---|---|---|
| firstName | string | |
| lastName | string | |
| string | ||
| company? | string | |
| notes? | string | |
| hostUserId | string | Appspace user UUID who hosts the drop-in (receives notification) |
| hostEmail | string | Same user's email |
| resourceId? | string | Optional reservation resource UUID (routes to that resource's Concierges) |
| durationMinutes | number | Length of the drop-in invitation in minutes |
| visitorType | string | |
| purpose | string | |
| timezone | string | IANA timezone for the invitation (e.g. 'America/New_York'). Default 'UTC'. |
fn listEvents(startAt?: string, endAt?: string, maxItems?: number)
Query visitor events (the runtime instances of invitations — when visitors are actually checking in/out).
| Argument | Type | Description |
|---|---|---|
| startAt? | string | |
| endAt? | string | |
| maxItems? | number |
fn checkin(eventId: string, visitorId: string)
Check a visitor in to an event.
| Argument | Type | Description |
|---|---|---|
| eventId | string | |
| visitorId | string |
fn checkout(eventId: string, visitorId: string)
Check a visitor out of an event.
| Argument | Type | Description |
|---|---|---|
| eventId | string | |
| visitorId | string |
Resources
visitor(infinite)— Visitor record in the Appspace Visitor Management system
visitorConfiguration(1d)— Visitor Management configuration for the account — required fields, custom field definitions, visit purposes, types, retention, and notification settings (the rules that drive Teams Passport / push / email routing)
invitation(infinite)— Visitor invitation — links visitors to hosts/resources and triggers Appspace's notification chain (Teams Passport bot, in-app push, Concierge, email)
04Previous Versions
2026.05.27.1May 27, 2026
Modernization: live pre-flight checks, idempotency, writeResource fixes for mutation results per audit. No breaking API changes.
2026.05.26.1May 26, 2026
Align model version fields with manifest (2026.05.26.1); republish under swamp 20260526 conventions
2026.05.05.1May 5, 2026
Modified 1 models
2026.04.27.1Apr 27, 2026
05Stats
A
100 / 100
Downloads
10
Archive size
68.3 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
06Platforms
07Labels