From b2487ea4a113ce17a080ccab9b4c4139813e8810 Mon Sep 17 00:00:00 2001 From: John Kaster Date: Wed, 4 Aug 2021 16:40:56 -0700 Subject: [PATCH] fix: documentation refs and notes for Typescript SDK and more (#783) * fix: documentation refs and notes Also address some reported issues Closes #447,#487 * update example blurb * correct packages note level * remove a support@looker.com reference --- README.md | 8 --- docs/byosdk.md | 82 +++++++++++++++--------------- docs/cors.md | 14 ++--- docs/paging.md | 3 +- docs/rationale.md | 2 +- examples/ruby/create_themes.rb | 6 +-- examples/typescript/README.md | 18 +++++-- packages/api-explorer/CHANGELOG.md | 2 +- packages/sdk-node/README.md | 14 +++++ packages/sdk/README.md | 24 +++++++-- packages/wholly-sheet/README.md | 4 +- python/setup.py | 2 +- 12 files changed, 102 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index a0db20661..350ca2fce 100644 --- a/README.md +++ b/README.md @@ -269,11 +269,3 @@ Configuration variables should be processed as follows: - if an environment variable exists, apply the value - if a configuration value is explicitly in code, apply that value - if a command-line switch is supported, apply that value - -## Very important note regarding the Looker TypeScript SDK - -The Looker TypeScript SDK has been refactored so that node dependencies do not pollute browser usage of the SDK (the node dependencies are not available in the browser and can cause compile errors). There are now three packages available on npm: - -1. `@looker/sdk` - contains the Looker API methods. -2. `@looker/sdk-rtl` - contains a run time library needed to invoke the Looker API methods. Referencing the `@looker/sdk` as a dependency should automatically pull this package in. -3. `@looker/sdk-node` - contains the dependendencies needed to run the Looker SDK in a node environment. Do NOT include this package if you are using the Looker SDK in a browser. You MUST include this package if you are using `node` or `ts-node`. diff --git a/docs/byosdk.md b/docs/byosdk.md index 5bcad1933..1c8c82585 100644 --- a/docs/byosdk.md +++ b/docs/byosdk.md @@ -9,19 +9,19 @@ The high-level steps for building a new Language SDK include: 1. Create the language/platform [run-time library](#run-time-library) (RTL) 1. Create the Language SDK [code generator](#code-generator) by descending from - [codeGen.ts](/packages/sdk-codegen/src/codeGen.ts) or perhaps the - [TypeScript generator](/packages/sdk-codegen/src/typescript.gen.ts) or [Python generator](/packages/sdk-codegen/src/python.gen.ts) + [codeGen.ts](../packages/sdk-codegen/src/codeGen.ts) or perhaps the + [TypeScript generator](../packages/sdk-codegen/src/typescript.gen.ts) or [Python generator](../packages/sdk-codegen/src/python.gen.ts) 1. Create [unit](#unit-tests) and [functional](#functional-or-integration-tests) tests 1. Complete the configuration of items for [CI/CD](#cicd) (where applicable) When implementing the syntax and features for the new language SDK, keep in mind the principles described in the -[Codegen rationale](/docs/rationale.md) documentation: +[Codegen rationale](rationale.md) documentation: -- [consistency](/docs/rationale.md#consistency), -- [discoverability](/docs/rationale.md#discoverability), and -- [correctness](/docs/rationale.md#correctness). +- [consistency](rationale.md#consistency), +- [discoverability](rationale.md#discoverability), and +- [correctness](rationale.md#correctness). Most examples in this document will use the TypeScript SDK, which is typically our lead language SDK the other SDKs follow. The other language SDK implementations found in this repository will have similarly named or designed classes. @@ -41,21 +41,21 @@ all generated files must use exactly the same RTL code. Any method of secure retrieval of API credentials and server locations can be supported by adopting the configuration provider pattern used by the reference SDKs. To support quickly getting started with an SDK, the existing SDKs support -`.ini` file style configuration both for [configuring the code generator](/README.md#configuring-lookerini) and as a +`.ini` file style configuration both for [configuring the code generator](../README.md#configuring-lookerini) and as a default configuration file. All SDKs implement something like a `readConfig() -> [String: String]` method that can be overridden to customize how -to determine configuration values. See [securing your SDK credentials](/README.md#securing-your-sdk-credentials) for more information +to determine configuration values. See [securing your SDK credentials](../README.md#securing-your-sdk-credentials) for more information on this topic, including links to `readConfig()` examples. -The TypeScript SDK configuration support is in [`apiSettings.ts`](/packages/sdk-rtl/src/apiSettings.ts). +The TypeScript SDK configuration support is in [`apiSettings.ts`](../packages/sdk-rtl/src/apiSettings.ts). Once the RTL can read the configuration values for `base_url` and API credentials, the HTTP request processor and `AuthSession` implementation work can begin. If the Language SDK supports environment variable, configuration values can also be set via -[environment variables](/README.md#environment-variable-configuration). -[Precedence rules](/README.md#configuration-variable-precedence) should also be implemented. +[environment variables](../README.md#environment-variable-configuration). +[Precedence rules](../README.md#configuration-variable-precedence) should also be implemented. **Note**: By design, SDKs never retain API credentials in runtime memory, but only use them when required to authenticate. @@ -178,7 +178,7 @@ export interface ITransport { } ``` -**Note**: The latest version of these interfaces can always be found in [transport.ts](/packages/sdk-rtl/src/transport.ts) +**Note**: The latest version of these interfaces can always be found in [transport.ts](../packages/sdk-rtl/src/transport.ts) The `ITransportSettings` interface shows the default properties for all HTTP requests and can also be used to override request settings for an individual HTTP request. @@ -314,7 +314,7 @@ This section discusses how parameters should be processed by the run-time **befo When the codegen project began, there was one method of authenticating for Looker API requests, which was providing the API credentials `client_id` and `client_secret` to the API. `AuthSession` is commonly the name of this class. Due to the complexities of Node vs. Browser implementations and authentication methods, the reference -implementation for the TypeScript SDK is called [`NodeSession`](/packages/sdk-rtl/src/nodeSession.ts) but for this +implementation for the TypeScript SDK is called [`NodeSession`](../packages/sdk-rtl/src/nodeSession.ts) but for this document we'll pretend it's called `AuthSession`. Recent (Looker 7.6 and above) API implementations additionally offer an OAuth authentication flow for API calls. Both @@ -355,18 +355,18 @@ extension, the run-time environment can provide API authentication support witho When an SDK supports significantly different runtime behavior, use a different `AuthSession` implementation. For example, the TypeScript SDK has: -- [`CSRFSession`](/packages/sdk-rtl/src/CSRFSession.ts) for browser-based same-origin usage -- [`BrowserSession`](/packages/sdk-rtl/src/browserSession.ts) for browser-based CORS usage -- [`NodeSession`](/packages/sdk-rtl/src/nodeSession.ts) for node-based usage -- [`OAuthSession`](/packages/sdk-rtl/src/oauthSession.ts) for OAuth2-based usage -- [`ProxySession`](/packages/sdk-rtl/src/proxySession.ts) for proxy-based usage +- [`CSRFSession`](../packages/sdk-rtl/src/CSRFSession.ts) for browser-based same-origin usage +- [`BrowserSession`](../packages/sdk-rtl/src/browserSession.ts) for browser-based CORS usage +- [`NodeSession`](../packages/sdk-rtl/src/nodeSession.ts) for node-based usage +- [`OAuthSession`](../packages/sdk-rtl/src/oauthSession.ts) for OAuth2-based usage +- [`ProxySession`](../packages/sdk-rtl/src/proxySession.ts) for proxy-based usage ## Code generator -The code generator "template" is written in TypeScript. The `ICodegen` interface (currently found at the bottom of [`sdkModels.ts`](/packages/sdk-codegen/src/sdkModels.ts)) +The code generator "template" is written in TypeScript. The `ICodegen` interface (currently found at the bottom of [`sdkModels.ts`](../packages/sdk-codegen/src/sdkModels.ts)) describes the properties and methods used to generate an API language binding for an SDK. -[`codeGen.ts`](/packages/sdk-codegen/src/codeGen.ts) is the base implementation of all code generators, and is partially +[`codeGen.ts`](../packages/sdk-codegen/src/codeGen.ts) is the base implementation of all code generators, and is partially abstract. Specific generators must override these abstract methods. ### Prologues and Epilogues @@ -378,14 +378,14 @@ The various **Prologue** properties are for the standard SDK methods, streaming, ### Strong typing -We strongly prefer strong typing for language SDKs, as mentioned in [correctness](/docs/rationale.md#correctness). +We strongly prefer strong typing for language SDKs, as mentioned in [correctness](rationale.md#correctness). Some languages may not support strong typing or generics. In that case, we recommend using name/value pairs and verifying the names against the endpoint's specification at run-time before submitting the HTTP request to the endpoint. ### Methods -The `IMethod` interface in [`sdkModels.ts`](/packages/sdk-codegen/src/sdkModels.ts) describes the properties and methods +The `IMethod` interface in [`sdkModels.ts`](../packages/sdk-codegen/src/sdkModels.ts) describes the properties and methods to use for generating a method declaration. REST API endpoints return responses that vary in type. There is always at least one _success_ and one _error_ response type. @@ -405,24 +405,24 @@ request processor **must not** convert the response to `UTF8`. by optional parameters. If the language doesn't have "named parameter" support the generator supports generation of -[request structures](/docs/rationale.md#request-structures). TypeScript is a language without named parameter support, so a +[request structures](rationale.md#request-structures). TypeScript is a language without named parameter support, so a request interface is created for methods with complex arguments. The code generator's `needRequestTypes` property should -be set to `true` in this circumstance. In the [TypeScript generator](/packages/sdk-codegen/src/typescript.gen.ts), +be set to `true` in this circumstance. In the [TypeScript generator](../packages/sdk-codegen/src/typescript.gen.ts), the `methodHeaderDeclaration` function has this line: ```ts const requestType = this.requestTypeName(method) ``` -If the method requires a request type and `needRequestTypes` is `true`, the [`codeGen.ts`](/packages/sdk-codegen/src/codeGen.ts) +If the method requires a request type and `needRequestTypes` is `true`, the [`codeGen.ts`](../packages/sdk-codegen/src/codeGen.ts) implementation of `requestTypeName()` will get or create the existing request type and return its name as the result of the function. Refer to the TypeScript generator for more information if your language needs a request type. -See the TypeScript SDK [`methods.ts`](/packages/sdk/src/sdk/4.0/methods.ts) for method declaration examples. +See the TypeScript SDK [`methods.ts`](../packages/sdk/src/sdk/4.0/methods.ts) for method declaration examples. ### Models -The `IType` interface in [`sdkModels.ts`](/packages/sdk-codegen/src/sdkModels.ts) describes the properties and methods +The `IType` interface in [`sdkModels.ts`](../packages/sdk-codegen/src/sdkModels.ts) describes the properties and methods to use for generating a type declaration. Type declarations are less complex than model declarations. Once the general template for type declarations is defined, @@ -480,23 +480,23 @@ Here's an example `typeMap` for Kotlin: } ``` -See the TypeScript SDK [`models.ts`](/packages/sdk/src/sdk/4.0/models.ts) for type/structure declaration examples. +See the TypeScript SDK [`models.ts`](../packages/sdk/src/sdk/4.0/models.ts) for type/structure declaration examples. ### Streams Streaming declarations are basically the same as [Methods](#methods), but with a parameter for a streaming callback. -See the TypeScript SDK [`streams.ts`](/packages/sdk/src/sdk/4.0/streams.ts) for streaming method examples. +See the TypeScript SDK [`streams.ts`](../packages/sdk/src/sdk/4.0/streams.ts) for streaming method examples. ### API version tracking -The `constants` file (e.g. [`constants.ts`](/packages/sdk-rtl/src/constants.ts)) for an SDK has the Looker API version and Looker release version as variables. The update mechanism -for these variables is in [`reformatter.ts`](/packages/sdk-codegen-scripts/src/reformatter.ts). +The `constants` file (e.g. [`constants.ts`](../packages/sdk-rtl/src/constants.ts)) for an SDK has the Looker API version and Looker release version as variables. The update mechanism +for these variables is in [`reformatter.ts`](../packages/sdk-codegen-scripts/src/reformatter.ts). #### Code reformatting Some languages have command-line code reformatters readily available. If your SDK language has a code reformatter, -define it in [`reformatter.ts`](/packages/sdk-codegen-scripts/src/reformatter.ts) and the generated source code will automatically +define it in [`reformatter.ts`](../packages/sdk-codegen-scripts/src/reformatter.ts) and the generated source code will automatically be reformatted when the code generation is finishing up. ## Tests @@ -504,12 +504,12 @@ be reformatted when the code generation is finishing up. A minimum testing threshold must be met before a Language SDK can be accepted. This section describes the tests to implement for a Language SDK. -Files that support testing scenarios can be found in the [`test`](/test) folder. +Files that support testing scenarios can be found in the [`test`](../test) folder. -- [`data.yml`](/test/data.yml) contains test data that can be used to create functional tests. -- [`data.yml.json`](/test/data.yml) is automatically translated from `data.yml`. -- [`openApiRef.json`](/test/openApiRef.json) is a sample OpenAPI 3.x json-formatted Looker API specification -- [`swaggerRef.json`](/test/swaggerRef.json) is a sample OpenAPI 2.x (Swagger) json-formatted Looker API specification +- [`data.yml`](../test/data.yml) contains test data that can be used to create functional tests. +- [`data.yml.json`](../test/data.yml) is automatically translated from `data.yml`. +- [`openApiRef.json`](../test/openApiRef.json) is a sample OpenAPI 3.x json-formatted Looker API specification +- [`swaggerRef.json`](../test/swaggerRef.json) is a sample OpenAPI 2.x (Swagger) json-formatted Looker API specification ### Unit tests @@ -573,8 +573,8 @@ fun asBoolean(value: String?): Boolean? { - optional parameters -See [`sdkModels.spec.ts`](/packages/sdk-codegen/src/sdkModels.spec.ts) and -[`python.gen.spec.ts`](/packages/sdk-codegen/src/python.gen.spec.ts) for examples. +See [`sdkModels.spec.ts`](../packages/sdk-codegen/src/sdkModels.spec.ts) and +[`python.gen.spec.ts`](../packages/sdk-codegen/src/python.gen.spec.ts) for examples. ### Functional or integration tests @@ -597,7 +597,7 @@ the root of the repository, configured for a running Looker server. - streaming (if applicable) -See [`methods.spec.ts`](/packages/sdk/src/test/methods.spec.ts) and +See [`methods.spec.ts`](../packages/sdk/src/test/methods.spec.ts) and [`test_methods.py`](/python/tests/integration/api40/test_methods.py) examples. ## CI/CD @@ -619,7 +619,7 @@ publishing to their respective package managers. ### Smoke testing -When the Language SDK test suite is complete, add all or some parts of the tests to the [`smoke`](/bin/smoke) test script. +When the Language SDK test suite is complete, add all or some parts of the tests to the [`smoke`](../bin/smoke) test script. This way, tests for the Language SDK will be part of the entire SDK Codegen test suite. The smoke tests require the test/reference instance of Looker configured in `looker.ini` to be up and running. diff --git a/docs/cors.md b/docs/cors.md index ff2cc60a8..6fde780c3 100644 --- a/docs/cors.md +++ b/docs/cors.md @@ -3,7 +3,7 @@ Please thoroughly read [Looker's OAuth and CORS documentation](https://docs.looker.com/reference/api-and-integration/api-cors) before reading this document. It will answer most questions about using OAuth and CORS with Looker, and describes Looker's OAuth configuration steps. -Looker API 4.0 supports CORS requests and is used in conjunction with Looker's OAuth workflow. [`BrowserSession`](/packages/sdk-rtl/src/browserSession.ts) provides the CORS support in the Browser SDK. +Looker API 4.0 supports CORS requests and is used in conjunction with Looker's OAuth workflow. [`BrowserSession`](../packages/sdk-rtl/src/browserSession.ts) provides the CORS support in the Browser SDK. `BrowserSession` is the default Browser-based session manager for the Looker SDK for TypeScript/JavaScript. OAuth authentication steps for a browser application are: @@ -21,10 +21,10 @@ OAuth authentication steps for a browser application are: Included in this repository are scripts and source code that hopefully reduce the amount of effort and code required to use OAuth and CORS: -- [OAuth application registration](/packages/sdk-codegen-scripts/scripts/register.ts) is a Node script that can create and update an OAuth app configuration -- a sample OAuth application configuration file [`appconfig.json`](/packages/sdk-codegen-scripts/scripts/appconfig.json) has the configuration for the stand-alone [API Explorer](/packages/api-explorer) in this repository -- a working [`readConfig` override](/packages/run-it/src/utils/RunItSDK.ts) provides the values required by `OAuthSession` -- a working React-based [OAuth handler](/packages/run-it/src/scenes/OAuthScene) processes OAuth authentications and "logs in" the SDK +- [OAuth application registration](../packages/sdk-codegen-scripts/scripts/register.ts) is a Node script that can create and update an OAuth app configuration +- a sample OAuth application configuration file [`appconfig.json`](../packages/sdk-codegen-scripts/scripts/appconfig.json) has the configuration for the stand-alone [API Explorer](../packages/api-explorer) in this repository +- a working [`readConfig` override](../packages/run-it/src/utils/RunItSDK.ts) provides the values required by `OAuthSession` +- a working React-based [OAuth handler](../packages/run-it/src/scenes/OAuthScene) processes OAuth authentications and "logs in" the SDK ## SDK support @@ -38,7 +38,7 @@ Because the OAuth workflow redirects the browser page to the Looker instance to - `looker_url` is the url of the Looker application server, typically on port `9999` and **not** the API server, typically on port `19999`. - `redirect_uri` is the web application page that receives OAuth responses from the looker server, and **must match the `redirect_uri` used for the OAuth application registration**. -The code below is from the [RunIt readConfig() override](/packages/run-it/src/utils/RunItSDK.ts): +The code below is from the [RunIt readConfig() override](../packages/run-it/src/utils/RunItSDK.ts): ```ts readConfig(_section?: string): IApiSection { @@ -88,6 +88,6 @@ Therefore, `OAuthSession.login()` has three different branches: Because the OAuth `code` is retrieved from the current browser url, the final `OAuthSession.login()` must be called directly from the `redirect_uri` page. -[OAuthScene.tsx](/packages/run-it/src/scenes/OAuthScene/OAuthScene.tsx) shows how the `returnUrl` can be captured and used to go back to the original browser location requiring authentication. +[OAuthScene.tsx](../packages/run-it/src/scenes/OAuthScene/OAuthScene.tsx) shows how the `returnUrl` can be captured and used to go back to the original browser location requiring authentication. **NOTE**: `OAuthSession.activeToken` is **not** saved in `sessionStorage` so it will disappear if the browser page reloads. That's why `history.push()` is used to relocate the browser page for the React application. The `returnUrl` in `sessionStorage` is a relative URI for this same reason. diff --git a/docs/paging.md b/docs/paging.md index 9d42a4c80..9734a16fe 100644 --- a/docs/paging.md +++ b/docs/paging.md @@ -56,8 +56,7 @@ The current SDK-based paging pattern prototype is in the `@looker/sdk-rtl` TypeS ### Paging interface -The main routines that initialize SDK paging are the functions `pager` and `pageAll`, and the class `Paging` defined in [paging.ts](/packages/sdk-rtl/src/paging.ts). - +The main routines that initialize SDK paging are the functions `pager` and `pageAll`, and the class `Paging` defined in [paging.ts](../packages/sdk-rtl/src/paging.ts). ### Page iteration example diff --git a/docs/rationale.md b/docs/rationale.md index 75777618a..1b4ff5b68 100644 --- a/docs/rationale.md +++ b/docs/rationale.md @@ -186,7 +186,7 @@ This third-party tool loses some attributes during the conversion, so the SDK co ## Code generation -The [Python generator](/packages/sdk-codegen/src/python.gen.ts) and [TypeScript generator](/packages/sdk-codegen/src/typescript.gen.ts) descend from a common class declared in [codeGen.ts](/packages/sdk-codegen/src/codeGen.ts). The base `CodeGen` class implements the `ICodeGen` interface, which is the contract for all the language-specific options the generator needs to support. Expect to see the internal implementation of this source change throughout the beta process as we refine the generators. +The [Python generator](../packages/sdk-codegen/src/python.gen.ts) and [TypeScript generator](../packages/sdk-codegen/src/typescript.gen.ts) descend from a common class declared in [codeGen.ts](../packages/sdk-codegen/src/codeGen.ts). The base `CodeGen` class implements the `ICodeGen` interface, which is the contract for all the language-specific options the generator needs to support. Expect to see the internal implementation of this source change throughout the beta process as we refine the generators. ### Model declarations diff --git a/examples/ruby/create_themes.rb b/examples/ruby/create_themes.rb index 8034e70e5..4653b5b3f 100644 --- a/examples/ruby/create_themes.rb +++ b/examples/ruby/create_themes.rb @@ -7,9 +7,9 @@ :api_endpoint => ENV['LOOKERSDK_BASE_URL'] ) ​ -# NOTE: Custom themes needs to be enabled by Looker. -# Unless custom themes are enabled, only the automatically generated default theme can be used. -# Please contact your Account Manager or support@looker.com to update your license for this feature. +# NOTE: Custom themes needs to be enabled by Looker. +# Unless custom themes are enabled, only the automatically generated default theme can be used. +# Please contact your Account Manager or https://help.looker.com to update your license for this feature. # Example formatting for the theme details to be created # example_custom_theme = { diff --git a/examples/typescript/README.md b/examples/typescript/README.md index 4dc073ab5..00e6fa2c0 100644 --- a/examples/typescript/README.md +++ b/examples/typescript/README.md @@ -26,15 +26,23 @@ These examples assume that a `looker.ini` has been created in the root of the re - `yarn run-tile` - runs download dashboard tile example. - `yarn run-dashboard` - runs download dashboard example. -An important note on dependencies. The Looker typescript SDK consists of the following packages: +Some other dependencies may be required for the projects to build and run correctly on your local clone. -1. `@looker/sdk` - contains the Looker API methods. -2. `@looker/sdk-rtl` - contains a run time library needed to invoke the Looker API methods. Referencing the `@looker/sdk` as a dependency should automatically pull this package in. -3. `@looker/sdk-node` - contains dependencies needed to run the Looker SDK in a node environment. Do NOT include this package if you are using the Looker SDK in a browser. +```bash +yarn install @types/readable-stream @types/request @types/request-promise-native -D +``` + +## TypeScript SDK packages + +The Looker TypeScript SDK has different packages to prevent node dependencies being linked into browser usage of the SDK (the node dependencies are not available in the browser and can cause compilation errors). There are three packages for the Typescript SDK available on npm: + +1. `@looker/sdk-rtl` - contains a run time library needed to invoke the Looker API methods. Referencing the `@looker/sdk` as a dependency should automatically pull this package in. +2. `@looker/sdk` - contains the Looker API methods. +3. `@looker/sdk-node` - contains the dependencies needed to run the Looker SDK in a node environment. Do NOT include this package if you are using the Looker SDK in a browser. You MUST include this package if you are using `node` or `ts-node`. ## Example list -Very brief descriptions of the examples, and the link to the main example/project file are provided here. For more information on an example, look at the source file. +A very brief descriptions of the examples, and the link to the main example/project file are provided here. For more information on an example, look at the source file. ### General examples diff --git a/packages/api-explorer/CHANGELOG.md b/packages/api-explorer/CHANGELOG.md index 1438be13d..84b75ad73 100644 --- a/packages/api-explorer/CHANGELOG.md +++ b/packages/api-explorer/CHANGELOG.md @@ -332,4 +332,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Response types now have nested types correctly documented - The response type processing functions now have arguments for the number of levels to expand nested types - API explorer's default expansion depth is one level deep -- Added [`ExploreType`](/packages/api-explorer/src/components/ExploreType/ExploreType.tsx) and [`ExploreProperty`](/packages/api-explorer/src/components/ExploreType/ExploreProperty.tsx) components used to display responses and explore the type on the type page \ No newline at end of file +- Added [`ExploreType`](src/components/ExploreType/ExploreType.tsx) and [`ExploreProperty`](src/components/ExploreType/ExploreProperty.tsx) components used to display responses and explore the type on the type page diff --git a/packages/sdk-node/README.md b/packages/sdk-node/README.md index 5b0903821..26ceeb6fc 100644 --- a/packages/sdk-node/README.md +++ b/packages/sdk-node/README.md @@ -32,6 +32,20 @@ npm install @looker/sdk @looker/sdk-rtl @looker/sdk-node **Note**: If you are only intending to use the SDK in a browser, omit `@looker/sdk-node`. +Some other dependencies may be required for your project to build and run correctly. + +```bash +yarn install @types/readable-stream @types/request @types/request-promise-native -D +``` + +### TypeScript SDK packages + +The Looker TypeScript SDK has different packages to prevent node dependencies being linked into browser usage of the SDK (the node dependencies are not available in the browser and can cause compilation errors). There are three packages for the Typescript SDK available on npm: + +1. `@looker/sdk-rtl` - contains a run time library needed to invoke the Looker API methods. Referencing the `@looker/sdk` as a dependency should automatically pull this package in. +2. `@looker/sdk` - contains the Looker API methods. +3. `@looker/sdk-node` - contains the dependencies needed to run the Looker SDK in a node environment. Do NOT include this package if you are using the Looker SDK in a browser. You MUST include this package if you are using `node` or `ts-node`. + ### Configure the SDK for your Looker server **Note**: The `.ini` configuration for the Looker SDK is a sample implementation intended to speed up the initial development of Node applications using the Looker API. [Environment variables](#environment-variable-configuration) can also be used to configure the SDK. diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 81237312d..8d130ac47 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -30,21 +30,35 @@ Using `npm`: npm install @looker/sdk @looker/sdk-rtl ``` +Some other dependencies may be required for your project to build and run correctly. + +```bash +yarn install @types/readable-stream @types/request @types/request-promise-native -D +``` + +### TypeScript SDK packages + +The Looker TypeScript SDK has different packages to prevent node dependencies being linked into browser usage of the SDK (the node dependencies are not available in the browser and can cause compilation errors). There are three packages for the Typescript SDK available on npm: + +1. `@looker/sdk-rtl` - contains a run time library needed to invoke the Looker API methods. Referencing the `@looker/sdk` as a dependency should automatically pull this package in. +2. `@looker/sdk` - contains the Looker API methods. +3. `@looker/sdk-node` - contains the dependencies needed to run the Looker SDK in a node environment. Do NOT include this package if you are using the Looker SDK in a browser. You MUST include this package if you are using `node` or `ts-node`. + ### Authenticate your API calls -All requests to the Looker API server require an access token. For browser implementations, authentication is typically achieved via OAuth as [described in `cors.md`](/docs/cors.md) or a [Proxy Server](#using-a-proxy-for-authentication). +All requests to the Looker API server require an access token. For browser implementations, authentication is typically achieved via OAuth as [described in `cors.md`](../../docs/cors.md) or a [Proxy Server](#using-a-proxy-for-authentication). ### Use the SDK in your browser application Authenticating for the browser takes more setup than authenticating for use with a Node application. -The stand-alone version of the [Looker API Explorer](/packages/api-explorer) uses OAuth and the `BrowserSDK` to get an authentication token for Looker API requests. +The stand-alone version of the [Looker API Explorer](../api-explorer) uses OAuth and the `BrowserSDK` to get an authentication token for Looker API requests. -- [RunItSDK](/packages/run-it/src/utils/RunItSDK.ts) shows how to override `readConfig()` to get SDK configuration values. +- [RunItSDK](../run-it/src/utils/RunItSDK.ts) shows how to override `readConfig()` to get SDK configuration values. -- [RunItSDK tests](/packages/run-it/src/utils/RunItSDK.spec.ts) support debugging the flow of `RunItSDK`. +- [RunItSDK tests](../run-it/src/utils/RunItSDK.spec.ts) support debugging the flow of `RunItSDK`. -- The [OAuthScene](/packages/run-it/src/scenes/OAuthScene/OAuthScene.tsx) React component receives the OAuth response from the Looker server and logs the user in to retrieve the API authentication token. +- The [OAuthScene](../run-it/src/scenes/OAuthScene/OAuthScene.tsx) React component receives the OAuth response from the Looker server and logs the user in to retrieve the API authentication token. Looker's OAuth support makes it possible to build a Looker SDK application that only requires the browser. If a browser application can use a proxy server instead, or already uses an existing backend server, it may be simpler to [use a proxy for authentication](#using-a-proxy-for-authentication)/ diff --git a/packages/wholly-sheet/README.md b/packages/wholly-sheet/README.md index 17f267a7a..1fe9d35b6 100644 --- a/packages/wholly-sheet/README.md +++ b/packages/wholly-sheet/README.md @@ -6,9 +6,7 @@ This package contains routines for treating a GSheet (Google Sheet) as a databas [**WhollySheet**](src/WhollySheet.ts) is the base component for data table-like operations on GSheet tabs. -The original version of WhollySheet is the Python [sheets.py](/examples/python/hackathon_app/sheets.py) created for the initial Looker Hackathon registration application in 2019. - -WhollySheet was ported to TypeScript for the new Looker-based [Hackathon application](/packages/hackathon) using the [Looker Extension Framework](https://docs.looker.com/data-modeling/extension-framework/extension-framework-intro). +WhollySheet was ported from Python to TypeScript for the new Looker-based [Hackathon application](../../packages/hackathon) using the [Looker Extension Framework](https://docs.looker.com/data-modeling/extension-framework/extension-framework-intro). ## SheetSDK diff --git a/python/setup.py b/python/setup.py index 44cfefb99..ea4405207 100644 --- a/python/setup.py +++ b/python/setup.py @@ -45,7 +45,7 @@ setup( author="Looker Data Sciences, Inc.", - author_email="support@looker.com", + author_email="Looker Team ", description="Looker API 3.1", install_requires=REQUIRES, license="MIT",