@tak-ps/node-tak 12.29.0 → 12.31.0

package/lib/api/user-management.ts

@@ -0,0 +1,326 @@
+import { Type, Static } from '@sinclair/typebox';
+import Commands, { CommandOutputFormat, type ParsedArgs } from '../commands.js';
+
+const GroupLists = {
+    groupList: Type.Optional(Type.Array(Type.String())),
+    groupListIN: Type.Optional(Type.Array(Type.String())),
+    groupListOUT: Type.Optional(Type.Array(Type.String()))
+};
+
+export const UserManagementUsername = Type.Object({
+    username: Type.String()
+});
+
+export const UserManagementGroupName = Type.Object({
+    groupname: Type.String()
+});
+
+export const UserManagementNewUser = Type.Object({
+    username: Type.String(),
+    password: Type.String(),
+    ...GroupLists
+});
+
+export const UserManagementBulkUsers = Type.Object({
+    usernameExpression: Type.String({ description: 'Username pattern containing [N] which is replaced by each integer from startN to endN' }),
+    startN: Type.Integer(),
+    endN: Type.Integer(),
+    ...GroupLists
+});
+
+export const UserManagementUserPassword = Type.Object({
+    username: Type.String(),
+    password: Type.String()
+});
+
+export const UserManagementUserGroups = Type.Object({
+    username: Type.String(),
+    ...GroupLists
+});
+
+export const UserManagementGroupUsers = Type.Object({
+    groupname: Type.String(),
+    usersInGroupList: Type.Optional(Type.Array(Type.String())),
+    usersInGroupListIN: Type.Optional(Type.Array(Type.String())),
+    usersInGroupListOUT: Type.Optional(Type.Array(Type.String()))
+});
+
+export const UserManagementList_Username = Type.Array(UserManagementUsername);
+export const UserManagementList_GroupName = Type.Array(UserManagementGroupName);
+export const UserManagementList_UserPassword = Type.Array(UserManagementUserPassword);
+
+export const UserManagementUserGroupsResponse = Type.Object({
+    username: Type.String(),
+    groupList: Type.Array(Type.String()),
+    groupListIN: Type.Array(Type.String()),
+    groupListOUT: Type.Array(Type.String())
+});
+
+export const UserManagementGroupUsersResponse = Type.Object({
+    groupname: Type.String(),
+    usersInGroupList: Type.Array(Type.String()),
+    usersInGroupListIN: Type.Array(Type.String()),
+    usersInGroupListOUT: Type.Array(Type.String())
+});
+
+/**
+ * Manage File (non-LDAP) User Accounts on TAK Server
+ *
+ * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api TAK Server Docs}.
+ */
+export default class UserManagementCommands extends Commands {
+    schema = {
+        'list-users': {
+            description: 'List File Users',
+            params: Type.Object({}),
+            query: Type.Object({}),
+            formats: [ CommandOutputFormat.JSON ]
+        },
+        'list-groups': {
+            description: 'List Group Names used by File Users',
+            params: Type.Object({}),
+            query: Type.Object({}),
+            formats: [ CommandOutputFormat.JSON ]
+        },
+        'user-groups': {
+            description: 'List Groups for a given File User',
+            params: Type.Object({ username: Type.String() }),
+            query: Type.Object({}),
+            formats: [ CommandOutputFormat.JSON ]
+        },
+        'group-users': {
+            description: 'List File Users in a given Group',
+            params: Type.Object({ group: Type.String() }),
+            query: Type.Object({}),
+            formats: [ CommandOutputFormat.JSON ]
+        },
+        'delete-user': {
+            description: 'Delete a File User',
+            params: Type.Object({ username: Type.String() }),
+            query: Type.Object({}),
+            formats: [ CommandOutputFormat.JSON ]
+        }
+    }
+
+    async cli(args: ParsedArgs): Promise<object | string> {
+        if (args._[3] === 'list-users') {
+            const list = await this.listUsers();
+
+            if (args.format === 'json') {
+                return list;
+            } else {
+                return list.map((user) => user.username).join('\n');
+            }
+        } else if (args._[3] === 'list-groups') {
+            const list = await this.listGroups();
+
+            if (args.format === 'json') {
+                return list;
+            } else {
+                return list.map((group) => group.groupname).join('\n');
+            }
+        } else if (args._[3] === 'user-groups') {
+            if (!args._[4]) throw new Error('username must be provided');
+
+            const user = await this.userGroups(args._[4]);
+
+            if (args.format === 'json') {
+                return user;
+            } else {
+                return [
+                    `${user.username}`,
+                    `  BOTH: ${user.groupList.join(', ')}`,
+                    `  IN:   ${user.groupListIN.join(', ')}`,
+                    `  OUT:  ${user.groupListOUT.join(', ')}`
+                ].join('\n');
+            }
+        } else if (args._[3] === 'group-users') {
+            if (!args._[4]) throw new Error('group must be provided');
+
+            const group = await this.groupUsers(args._[4]);
+
+            if (args.format === 'json') {
+                return group;
+            } else {
+                return [
+                    `${group.groupname}`,
+                    `  BOTH: ${group.usersInGroupList.join(', ')}`,
+                    `  IN:   ${group.usersInGroupListIN.join(', ')}`,
+                    `  OUT:  ${group.usersInGroupListOUT.join(', ')}`
+                ].join('\n');
+            }
+        } else if (args._[3] === 'delete-user') {
+            if (!args._[4]) throw new Error('username must be provided');
+
+            await this.deleteUser(args._[4]);
+
+            return `Deleted ${args._[4]}`;
+        } else {
+            throw new Error('Unsupported Subcommand');
+        }
+    }
+
+    /**
+     * Create a new File User
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/createOrUpdateFileUser TAK Server Docs}.
+     */
+    async createUser(user: Static<typeof UserManagementNewUser>): Promise<void> {
+        const url = new URL('/Marti/api/user-management/api/new-user', this.api.url);
+
+        await this.api.fetch(url, {
+            method: 'POST',
+            body: {
+                username: user.username,
+                password: user.password,
+                groupList: user.groupList ?? [],
+                groupListIN: user.groupListIN ?? [],
+                groupListOUT: user.groupListOUT ?? []
+            }
+        });
+    }
+
+    /**
+     * Create File Users in bulk from a username expression containing `[N]`
+     * Passwords are generated by the server and only returned once
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/createFileUsersInBulk TAK Server Docs}.
+     */
+    async createUsers(
+        bulk: Static<typeof UserManagementBulkUsers>
+    ): Promise<Static<typeof UserManagementList_UserPassword>> {
+        const url = new URL('/Marti/api/user-management/api/new-users', this.api.url);
+
+        return await this.api.fetch(url, {
+            method: 'POST',
+            body: {
+                usernameExpression: bulk.usernameExpression,
+                startN: bulk.startN,
+                endN: bulk.endN,
+                groupList: bulk.groupList ?? [],
+                groupListIN: bulk.groupListIN ?? [],
+                groupListOUT: bulk.groupListOUT ?? []
+            }
+        });
+    }
+
+    /**
+     * List all File Users
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/getAllUsers_3 TAK Server Docs}.
+     */
+    async listUsers(): Promise<Static<typeof UserManagementList_Username>> {
+        const url = new URL('/Marti/api/user-management/api/list-users', this.api.url);
+
+        return await this.api.fetch(url, {
+            method: 'GET'
+        });
+    }
+
+    /**
+     * Get the Groups associated with a File User
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/getGroupsForUsers TAK Server Docs}.
+     */
+    async userGroups(username: string): Promise<Static<typeof UserManagementUserGroupsResponse>> {
+        const url = new URL(`/Marti/api/user-management/api/get-groups-for-user/${encodeURIComponent(username)}`, this.api.url);
+
+        return await this.api.fetch(url, {
+            method: 'GET'
+        });
+    }
+
+    /**
+     * Change the password of a File User
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/changeUserPassword TAK Server Docs}.
+     */
+    async changePassword(user: Static<typeof UserManagementUserPassword>): Promise<void> {
+        const url = new URL('/Marti/api/user-management/api/change-user-password', this.api.url);
+
+        await this.api.fetch(url, {
+            method: 'PUT',
+            body: {
+                username: user.username,
+                password: user.password
+            }
+        });
+    }
+
+    /**
+     * Replace the Groups associated with a File User
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/updateGroupsForUser TAK Server Docs}.
+     */
+    async updateUserGroups(user: Static<typeof UserManagementUserGroups>): Promise<void> {
+        const url = new URL('/Marti/api/user-management/api/update-groups', this.api.url);
+
+        await this.api.fetch(url, {
+            method: 'PUT',
+            body: {
+                username: user.username,
+                groupList: user.groupList ?? [],
+                groupListIN: user.groupListIN ?? [],
+                groupListOUT: user.groupListOUT ?? []
+            }
+        });
+    }
+
+    /**
+     * Replace the File Users associated with a Group
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/updateUsersForGroup TAK Server Docs}.
+     */
+    async updateGroupUsers(group: Static<typeof UserManagementGroupUsers>): Promise<void> {
+        const url = new URL('/Marti/api/user-management/api/update-group-users', this.api.url);
+
+        await this.api.fetch(url, {
+            method: 'PUT',
+            body: {
+                groupname: group.groupname,
+                usersInGroupList: group.usersInGroupList ?? [],
+                usersInGroupListIN: group.usersInGroupListIN ?? [],
+                usersInGroupListOUT: group.usersInGroupListOUT ?? []
+            }
+        });
+    }
+
+    /**
+     * Delete a File User
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/deleteUser_1 TAK Server Docs}.
+     */
+    async deleteUser(username: string): Promise<void> {
+        const url = new URL(`/Marti/api/user-management/api/delete-user/${encodeURIComponent(username)}`, this.api.url);
+
+        await this.api.fetch(url, {
+            method: 'DELETE'
+        });
+    }
+
+    /**
+     * List all Group Names used by File Users
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/getAllGroupNames TAK Server Docs}.
+     */
+    async listGroups(): Promise<Static<typeof UserManagementList_GroupName>> {
+        const url = new URL('/Marti/api/user-management/api/list-groupnames', this.api.url);
+
+        return await this.api.fetch(url, {
+            method: 'GET'
+        });
+    }
+
+    /**
+     * Get the File Users in a Group along with their IN/OUT/BOTH direction
+     *
+     * {@link https://docs.tak.gov/api/takserver#tag/file-user-account-management-api/operation/getUsersInGroup TAK Server Docs}.
+     */
+    async groupUsers(group: string): Promise<Static<typeof UserManagementGroupUsersResponse>> {
+        const url = new URL(`/Marti/api/user-management/api/users-in-group/${encodeURIComponent(group)}`, this.api.url);
+
+        return await this.api.fetch(url, {
+            method: 'GET'
+        });
+    }
+}

package/lib/api.ts

@@ -6,6 +6,7 @@ import Locate from './api/locate.js';
 import Mission, { MissionSubscriberRole } from './api/mission.js';
 import MissionInvite, { MissionInviteType } from './api/mission-invite.js';
 import MissionLog from './api/mission-log.js';
+import MissionProperty from './api/mission-property.js';
 import MissionLayer, { MissionLayerType } from './api/mission-layer.js';
 import Credentials from './api/credentials.js';
 import Security from './api/security.js';
@@ -20,6 +21,7 @@ import Group from './api/groups.js';
 import Subscription from './api/subscriptions.js';
 import Video from './api/video.js';
 import Export from './api/export.js';
+import UserManagement from './api/user-management.js';
 import Err from '@openaddresses/batch-error';
 import { TAKServerError, isHTML } from './utils/html-error.js';
 import * as auth from './auth.js';
@@ -75,6 +77,7 @@ export const CommandList: Record<string, keyof TAKAPI> = {
     mission: 'Mission',
     'mission-invite': 'MissionInvite',
     'mission-log': 'MissionLog',
+    'mission-property': 'MissionProperty',
     'mission-layer': 'MissionLayer',
     credential: 'Credentials',
     certificate: 'Certificate',
@@ -88,7 +91,8 @@ export const CommandList: Record<string, keyof TAKAPI> = {
     video: 'Video',
     export: 'Export',
     query: 'Query',
-    file: 'Files'
+    file: 'Files',
+    'user-management': 'UserManagement'
 }
 
 /**
@@ -105,6 +109,7 @@ export default class TAKAPI {
     Iconsets: Iconsets;
     Mission: Mission;
     MissionLog: MissionLog;
+    MissionProperty: MissionProperty;
     MissionInvite: MissionInvite;
     MissionLayer: MissionLayer;
     Credentials: Credentials;
@@ -120,6 +125,7 @@ export default class TAKAPI {
     Export: Export;
     Query: Query;
     Files: Files;
+    UserManagement: UserManagement;
 
     constructor(url: URL, auth: auth.APIAuth) {
         this.url = url;
@@ -136,6 +142,7 @@ export default class TAKAPI {
         this.Iconsets = new Iconsets(this);
         this.Mission = new Mission(this);
         this.MissionLog = new MissionLog(this);
+        this.MissionProperty = new MissionProperty(this);
         this.MissionInvite = new MissionInvite(this);
         this.MissionLayer = new MissionLayer(this);
         this.Client = new Client(this);
@@ -147,6 +154,7 @@ export default class TAKAPI {
         this.Injectors = new Injectors(this);
         this.Repeater = new Repeater(this);
         this.Files = new Files(this);
+        this.UserManagement = new UserManagement(this);
     }
 
     static async init(url: URL, auth: auth.APIAuth): Promise<TAKAPI> {
@@ -242,6 +250,7 @@ export {
     Mission,
     MissionInvite,
     MissionLog,
+    MissionProperty,
     MissionLayer,
     Client,
     Credentials,
@@ -256,6 +265,7 @@ export {
     Subscription,
     Video,
     Export,
+    UserManagement,
     MissionSubscriberRole,
     MissionLayerType,
     MissionInviteType

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@tak-ps/node-tak",
     "type": "module",
-    "version": "12.29.0",
+    "version": "12.31.0",
     "description": "Lightweight JavaScript library for communicating with TAK Server",
     "author": "Nick Ingalls <nick@ingalls.ca>",
     "main": "dist/index.js",

package/test/mission-property.test.ts

@@ -0,0 +1,95 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Readable } from 'node:stream';
+import { Client } from 'undici';
+import type { Dispatcher } from 'undici';
+import TAKAPI from '../lib/api.js';
+import { APIAuthCertificate } from '../lib/auth.js';
+
+type RequestArgs = Parameters<Client['request']>[0];
+
+const GUID = '9ba05e1d-970f-49e1-a153-7216fecf5279';
+
+function mockResponse(statusCode: number, contentType: string, body: string): Dispatcher.ResponseData {
+    return {
+        statusCode,
+        headers: { 'content-type': contentType },
+        body: Readable.from([Buffer.from(body)]),
+        trailers: {}
+    } as unknown as Dispatcher.ResponseData;
+}
+
+async function capture(
+    response: string,
+    fn: (api: TAKAPI) => Promise<unknown>
+): Promise<{ requests: RequestArgs[], result: unknown }> {
+    const originalRequest = Client.prototype.request;
+    const requests: RequestArgs[] = [];
+
+    Client.prototype.request = async function(opts: RequestArgs): Promise<Dispatcher.ResponseData> {
+        requests.push(opts);
+        return mockResponse(200, response ? 'application/json' : 'text/plain', response);
+    };
+
+    try {
+        const api = new TAKAPI(new URL('https://tak.example.com'), new APIAuthCertificate('cert', 'key'));
+        const result = await fn(api);
+        return { requests, result };
+    } finally {
+        Client.prototype.request = originalRequest;
+    }
+}
+
+const ITEM = JSON.stringify({ version: '3', type: 'com.bbn.marti.sync.model.MissionProperty', data: { key: 'test.hello', value: 'world' } });
+const LIST = JSON.stringify({ version: '3', type: 'com.bbn.marti.sync.model.MissionProperty', data: [{ key: 'test.hello', value: 'world' }] });
+
+test('MissionProperty.list uses the guid properties endpoint with a prefix filter', async () => {
+    const { requests, result } = await capture(LIST, (api) => api.MissionProperty.list(GUID, { prefix: 'test.' }));
+
+    assert.equal(requests.length, 1);
+    assert.equal(requests[0].method, 'GET');
+    assert.equal(requests[0].path, `/Marti/api/missions/guid/${GUID}/properties?prefix=test.`);
+    assert.deepEqual((result as { data: unknown }).data, [{ key: 'test.hello', value: 'world' }]);
+});
+
+test('MissionProperty.get encodes the key in the path', async () => {
+    const { requests } = await capture(ITEM, (api) => api.MissionProperty.get(GUID, 'a b'));
+
+    assert.equal(requests[0].method, 'GET');
+    assert.equal(requests[0].path, `/Marti/api/missions/guid/${GUID}/properties/a%20b`);
+});
+
+test('MissionProperty.set PUTs key/value with creatorUid as a query param', async () => {
+    const { requests } = await capture(ITEM, (api) => api.MissionProperty.set(GUID, {
+        key: 'test.hello',
+        value: 'world',
+        creatorUid: 'alice'
+    }));
+
+    assert.equal(requests[0].method, 'PUT');
+    assert.equal(requests[0].path, `/Marti/api/missions/guid/${GUID}/properties?creatorUid=alice`);
+    assert.deepEqual(JSON.parse(String(requests[0].body)), { key: 'test.hello', value: 'world' });
+});
+
+test('MissionProperty.delete removes a single key', async () => {
+    const { requests } = await capture('', (api) => api.MissionProperty.delete(GUID, 'test.hello', 'alice'));
+
+    assert.equal(requests[0].method, 'DELETE');
+    assert.equal(requests[0].path, `/Marti/api/missions/guid/${GUID}/properties/test.hello?creatorUid=alice`);
+});
+
+test('MissionProperty.deleteAll removes every key', async () => {
+    const { requests } = await capture('', (api) => api.MissionProperty.deleteAll(GUID, 'alice'));
+
+    assert.equal(requests[0].method, 'DELETE');
+    assert.equal(requests[0].path, `/Marti/api/missions/guid/${GUID}/properties?creatorUid=alice`);
+});
+
+test('MissionProperty resolves a mission name to its GUID first', async () => {
+    const MISSION = JSON.stringify({ version: '3', type: 'Mission', data: [{ name: 'kv-test', guid: GUID }] });
+    const { requests } = await capture(MISSION, (api) => api.MissionProperty.list('kv-test'));
+
+    assert.equal(requests.length, 2);
+    assert.equal(requests[0].path, '/Marti/api/missions/kv-test');
+    assert.equal(requests[1].path, `/Marti/api/missions/guid/${GUID}/properties`);
+});