bimplus-websdk 1.0.63 → 1.0.65

package/.github/instructions/typescript-declarations.instructions.md

@@ -0,0 +1,116 @@
+---
+applyTo: "websdk/types/bimplus-websdk.d.ts"
+---
+
+# Bimplus WebSDK — TypeScript Declarations
+
+## File Structure
+
+All declarations live inside a single module augmentation — never add top-level exports outside it:
+
+```ts
+declare module 'bimplus-websdk' {
+  // all types here
+}
+```
+
+---
+
+## Base Type Aliases
+
+These are already defined — use them for parameter and return types instead of plain `string`:
+
+```ts
+Guid                // string UUID
+ProjectId           // Guid
+ModelId             // Guid
+LayerId             // Guid
+DivisionTopologyId  // Guid
+RevisionId          // string
+TeamSlug            // string
+AccessToken         // string
+AccessTokenType     // string
+HTML                // string
+```
+
+---
+
+## Pattern for a New Resource Module
+
+For each new `src/Api/MyResource.js`, add three things:
+
+### 1. A data interface
+
+```ts
+export interface MyResourceData {
+    id: Guid;
+    name: string;
+    // match field names from the REST API response exactly
+}
+```
+
+### 2. A class declaration
+
+```ts
+export class MyResource {
+    constructor(api: Api);
+    get(id?: Guid): Promise<MyResourceData | MyResourceData[]>;
+    post(data: string): Promise<MyResourceData>;
+    put(id: Guid, data: string): Promise<MyResourceData>;
+    delete(id: Guid): Promise<void>;
+}
+```
+
+### 3. A property on the `Api` class
+
+Add to the existing `Api` class body, matching the exact property name from `src/Api/Api.js`:
+
+```ts
+// In src/Api/Api.js: this.myResource = new MyResource(this)
+myResource: MyResource;
+```
+
+---
+
+## Conventions
+
+- All async methods return `Promise<T>` — never use jQuery types (`JQuery.Promise`, `$.Deferred`) in declarations
+- For optional parameters use `?`: `get(id?: Guid)`
+- For methods that return a single item or an array: `Promise<T | T[]>`
+- `data` parameters passed as `JSON.stringify(...)` in the source are typed as `string`
+- Keep parameter names consistent with the JSDoc `@param` names in the corresponding source file
+- For complex `data` shapes that are always structured objects (not stringified), define a dedicated interface and use it: `post(data: MyResourceData): Promise<MyResourceData>`
+- For query-param-only options (e.g. `additionalParams`), use a typed object or the existing `AdditionalParams` alias:
+  ```ts
+  type AdditionalParams = { [key: string]: string };
+  ```
+
+---
+
+## Api Class Declaration
+
+The `Api` class in this file is the single source of truth for TypeScript consumers. Every namespace instantiated in `src/Api/Api.js` must appear as a property:
+
+```ts
+export class Api {
+    constructor(config?: ApiConfig);
+    setAccessToken(token: AccessToken): void;
+    setTokenType(tokenType: AccessTokenType): void;
+    setAccessTokenAndType(token: AccessToken, tokenType: AccessTokenType): void;
+    getAccessToken(): AccessToken;
+    getTokenType(): AccessTokenType;
+    getAccessTokenAndType(): { token: AccessToken; tokenType: AccessTokenType };
+    setTeamSlug(slug: TeamSlug): void;
+    getTeamSlug(): TeamSlug;
+    getApiUrl(): string;
+    getApiTeamUrl(): string;
+
+    // resource namespaces
+    authorize: Authorize;
+    projects: Projects;
+    models: Models;
+    // ... one line per namespace
+}
+```
+
+When adding a new module, append its property in the same order it appears in the `Api` constructor in `src/Api/Api.js`.