{"id":19435293,"url":"https://github.com/masaar/ns-limp","last_synced_at":"2025-04-24T20:32:29.207Z","repository":{"id":35021973,"uuid":"191697781","full_name":"masaar/ns-limp","owner":"masaar","description":"Nativescript SDK for LIMP","archived":false,"fork":false,"pushed_at":"2023-01-07T06:47:17.000Z","size":4753,"stargazers_count":3,"open_issues_count":25,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-20T17:04:37.013Z","etag":null,"topics":["limp","nativescript","nativescript-angular","nativescript-plugin","sdk"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/masaar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-13T05:41:18.000Z","updated_at":"2024-05-30T16:46:04.000Z","dependencies_parsed_at":"2023-01-15T12:12:07.288Z","dependency_job_id":null,"html_url":"https://github.com/masaar/ns-limp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masaar%2Fns-limp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masaar%2Fns-limp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masaar%2Fns-limp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masaar%2Fns-limp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/masaar","download_url":"https://codeload.github.com/masaar/ns-limp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250704937,"owners_count":21473789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["limp","nativescript","nativescript-angular","nativescript-plugin","sdk"],"created_at":"2024-11-10T15:05:19.447Z","updated_at":"2025-04-24T20:32:28.517Z","avatar_url":"https://github.com/masaar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ns-limp\nOfficial NativeScript Angular SDK for [LIMP](https://github.com/masaar/ns-limp).\n\n# Quick Start\nThe current SDK has two dependencies:\n* `jsrasgin`\n* `nativescript-websockets`\nThe dependencies should be automatically installed with the library.\n\n## Install ns-limp for NativeScript\n```bash\ntns plugin add ns-limp\n```\n\n## How to Use\n1. Initiate the API, in your component, using :\n```typescript\nimport { Component, OnInit } from '@angular/core';\n\nimport { ApiService, Res } from 'ns-limp/api.service';\n\n@Component({\n\tselector: 'app-root',\n\ttemplateUrl: './app.component.html',\n\tstyleUrls: ['./app.component.css']\n})\nexport class AppComponent implements OnInit {\n\n\tconstructor(private api: ApiService) {}\n\n\tngOnInit() {\n\t\tthis.api.init({\n\t\t\tapi: 'ws://localhost:8081/ws',\n\t\t\tanonToken: '__ANON',\n\t\t\tauthAttrs: ['email']\n\t\t});\n\t}\n}\n```\n\n## SDK Config\nWhen initialising the SDK, you should pass an object matching the interface `SDKConfig`, which has the following attributes:\n1. `api` (Required): The URI of LIMP app you are connecting to.\n2. `anonToken` (Required): LIMP app `ANON_TOKEN`.\n3. `authAttrs` (Required): As of LIMP APIv5.8, LIMP apps don't have strict User module attrs structure. This includes the authentication attrs that are set per app. This attribute represents an `Array\u003cstring\u003e` referring to the same authentication attrs of the app.\n4. `debug` (Optional): A `Boolean` representing the debug mode status on the SDK. If `true`, you would see verbose messages in the browser console about messages transferred are received. Default `false`.\n5. `fileChunkSize` (Optional): A `Number` representing the chunk size in bytes of the files being uploaded as part of the process of pushing binary data to LIMP app. Default `512000`.\n6. `authHashLevel` (Optional): Either `5.0` or `5.6`. With the change to auth hash generation introduced in APIv5.6 of LIMP, some legacy apps are left without the ability to upgrade to APIv5.6 and beyond due to hashes difference. SDKv5.7 is adding `authHashLevel` to allow developers to use higher APIs and SDKs with legacy apps. Default `5.6`;\n\n# Best Practices\nYou can use the SDK 100% per your style of development, however we have some tips:\n\n## Session Reauth\nThe best practice to handle a `reauth` scenario is by attempting to `checkAuth` as soon as the connection with LIMP app is made. This can be made by subscribing to `inited$` subject which notifies subscriptions about any changes to SDK initialisation status reflected as `inited` attribute in the SDK. Which can be done like:\n```typescript\nthis.api.inited$.subscribe((init: boolean) =\u003e {\n\tif (init) {\n\t\t// SDK is inited and ready for your calls:\n\t\ttry {\n\t\t\t// Wrap in try..catch to handle error thrown if no credentials cached\n\t\t\tthis.api.checkAuth();\n\t\t} catch { }\n\t}\n}, (err: Res\u003cDoc\u003e) =\u003e {\n\tconsole.log('inited$.err', err);\n});\n```\n\n## Auth State Detection\nAlthough, you can detect the user auth state in the subscription of the calls `auth`, `reauth` and `checkAuth`, the best practice is to use the global `authed$` state `Subject`. You can do this by subscripting to `authed$` in the same component (usually `AppComponent`) you are initiating the SDK at. This assures a successful `checkAuth` as part of the `api.init` subscription can be handled. The model suggested is:\n```typescript\nthis.api.authed$.subscribe((session: Doc) =\u003e {\n\tif (session) {\n\t\tconsole.log('We are having an `auth` condition with session:', session);\n\t} else {\n\t\tconsole.log('We just got unauthenticated');\n\t}\n});\n```\n\n## Reconnecting on Disconnects\nWebsockets are always-alive connections. A lot can go wrong here resulting in the connection with your LIMP app. To make sure you can always get reconnected recall SDK `init` method upon SDK becoming not `inited`:\n```typescript\nimport { Component, OnInit } from '@angular/core';\n\nimport { ApiService, Res } from 'ns-limp/api.service';\n\n@Component({\n\tselector: 'app-root',\n\ttemplateUrl: './app.component.html',\n\tstyleUrls: ['./app.component.css']\n})\nexport class AppComponent implements OnInit {\n\n\tconstructor(private api: ApiService) {\n\t\tthis.api.inited$.subscribe((init: boolean) =\u003e {\n\t\t\tif (init) {\n\t\t\t\t// SDK is inited and ready for your calls:\n\t\t\t\ttry {\n\t\t\t\t\t// Wrap in try..catch to handle error thrown if no credentials cached\n\t\t\t\t\tthis.api.checkAuth();\n\t\t\t\t} catch { }\n\t\t\t} else {\n\t\t\t\t// SDK just got not inited, let's init SDK again:\n\t\t\t\tthis.init();\n\t\t\t}\n\t\t}, (err: Res\u003cDoc\u003e) =\u003e {\n\t\t\tconsole.log('inited$.err', err);\n\t\t});\n\t}\n\n\tngOnInit() {\n\t\tthis.init();\n\t}\n\n\tinit(): void {\n\t\tthis.api.init({\n\t\t\tapi: 'ws://localhost:8081/ws',\n\t\t\tanonToken: '__ANON',\n\t\t\tauthAttrs: ['email']\n\t\t});\n\t}\n}\n```\n\n# API Reference\n\n## `debug`\nA `Boolean` representing the debug mode status on the SDK. If `true`, you would see verbose messages in the browser console about messages transferred are received. Default `false`.\n\n## `fileChunkSize`\nA `Number` representing the chunk size in bytes of the files being uploaded as part of the process of pushing binary data to LIMP app. Default `512000`.\n\n## `session`\nA `Doc` object representing the current session. It has value only when the user is authenticated.\n\n## `authed`\nA `Boolean` storing the current state of user authentication.\n\n## `authed$`\nA `Subject\u003cBoolean | Doc\u003e` you can subscribe to handle changes to state of user authentication.\n\n## `init()`\nThe base method to initiate a connection with LIMP app. This method returns an `Observable` for chain subscription if for any reason you need to read every message being received from the API, however subscribing to it is not required. Method definition:\n```typescript\ninit(api: String, anonToken: String): Observable\u003cRes\u003cDoc\u003e\u003e { /*...*/ }\n```\n\n## `close()`\nThe method to close current connection with LIMP app. This method returns an `Observable` for chain subscription if for any reason you need to read the resposne of the `close` call, however subscribing to it is not required. Method definition:\n```typescript\nclose(): Observable\u003cRes\u003cDoc\u003e\u003e { /*...*/ }\n```\n\n## `auth()`\nThe method you can use to authenticate the user. This method returns an `Observable` for chain subscription if for any reason you need to read the response of the `auth` call, however subscribing to it is not required. Method definition:\n```typescript\nauth(authVar: string, authVal: string, password: string): Observable\u003cRes\u003cDoc\u003e\u003e { /*...*/ }\n```\n\n## `reauth()`\nThe method you can use to reauthenticate the user. The method would fail if no `sid` and `token` attrs are cached from earlier successful authentication call. This method is not supposed to be called directly, rather use [`checkAuth()`](#checkauth). This method returns an `Observable` for chain subscription if for any reason you need the response of the `reauth` call, however subscribing to it is not required. Method definition:\n```typescript\nreauth(sid: string = this.cache.get('sid'), token: string = this.cache.get('token')): Observable\u003cRes\u003cDoc\u003e\u003e { /*...*/ }\n```\n\n## `signout()`\nThe method you can use to `signout` the current user. Upon success, this methods removes all the cached attrs of the session. This method returns an `Observable` for chain subscription if for any reason you need the response of the `signout` call, however subscribing to it is not required. Method definition:\n```typescript\nsignout(): Observable\u003cRes\u003cDoc\u003e\u003e { /*...*/ }\n```\n\n## `checkAuth()`\nThe method to check whether there is a cached session and attempt to reauthenticate the user. This method would throw an error if no credentials are cached, thus you need to always wrap it in `try..catch`. This method returns an `Observable` for chain subscription if for any reason you need the response of the `checkAuth` call, however subscribing to it is not required. Method definition:\n```typescript\ncheckAuth(): Observable\u003cRes\u003cDoc\u003e\u003e { /*...*/ }\n```\n\n## `generateAuthHash()`\nThe method to use to generate authentication hashes. This is used internally for the [`auth()`](#auth) call. However, you also need this to generate the values when creating a user. Method definition:\n```typescript\ngenerateAuthHash(authVar: string, authVal: string, password: string): string { /*...*/ }\n```\n\n## `deleteWatch()`\nThe method to delete a watch in progress. You can pass the watch ID you want to delete or `__all` to delete all watches. This method returns an `Observable` for chain subscription if for any reason you need the response of the `deleteWatch` call, however subscribing to it is not required. Method definition:\n```typescript\ndeleteWatch(watch: string | '__all'): Observable\u003cRes\u003cDoc\u003e\u003e { /*...*/ }\n```\n\n## `call()`\nThe most important method in the SDK. This is the method you use to call different endpoints in your LIMP app. Although the `callArgs` object in the params is having full definition of all call attrs, you still usually only need to pass either `query` and/or `doc` in most of the cases. Third param `awaitAuth` specify wheter the call should be queued until session is authed. Method definition:\n```typescript\ncall(endpoint: string, callArgs: callArgs, awaitAuth: boolean = false): Observable\u003cRes\u003cDoc\u003e\u003e { /*...*/ }\n```\n\n# Contribution Guidelines\nThank you for your interest in `ns-limp`.\n\nPlease refer to [Contribution Guidelines](/CONTRIBUTING.md) for more details on contributing to this project.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasaar%2Fns-limp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmasaar%2Fns-limp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasaar%2Fns-limp/lists"}