diff --git a/.docs/content/0.index.md b/.docs/content/0.index.md index 581634c..29d9522 100644 --- a/.docs/content/0.index.md +++ b/.docs/content/0.index.md @@ -8,7 +8,7 @@ layout: page --- cta: - Get Started - - /guide/usage + - /get-started/introduction secondary: - Open on GitHub → - https://github.com/movie-web/providers diff --git a/.docs/content/1.Get Started/0.introduction.md b/.docs/content/1.Get Started/0.introduction.md index 9acabc5..a21f427 100644 --- a/.docs/content/1.Get Started/0.introduction.md +++ b/.docs/content/1.Get Started/0.introduction.md @@ -3,3 +3,5 @@ - What is this project - How does it work? - What environments can it be ran in? + +TODO diff --git a/.docs/content/1.Get Started/1.quick-start.md b/.docs/content/1.Get Started/1.quick-start.md index 070538f..0627f4b 100644 --- a/.docs/content/1.Get Started/1.quick-start.md +++ b/.docs/content/1.Get Started/1.quick-start.md @@ -1,8 +1,6 @@ # Quick start -- Prerequisites -- Install -- Scrape first item +## Installation Let's get started with `@movie-web/providers`. First lets install the package. @@ -22,11 +20,15 @@ Let's get started with `@movie-web/providers`. First lets install the package. To get started with scraping on the **server**, first you have to make an instance of the providers. -```ts -import { makeProviders, makeDefaultFetcher, targets } from '@movie-web/providers'; +::alert{type="warning"} +This snippet will only work on a **server**, for other environments, check out [Usage on X](../2.Essentials/0.usage-on-x.md). +:: + +```ts [index.ts (server)] +import { makeProviders, makeStandardFetcher, targets } from '@movie-web/providers'; // this is how the library will make http requests -const myFetcher = makeDefaultFetcher(fetch); +const myFetcher = makeStandardFetcher(fetch); // make an instance of the providers library const providers = makeProviders({ @@ -37,7 +39,8 @@ const providers = makeProviders({ }) ``` -Perfect, now we can start scraping a stream: +Perfect, this instance of the providers you can reuse everywhere where you need to. +Now lets actually scrape an item: ```ts [index.ts (server)] // fetch some data from TMDB @@ -51,7 +54,7 @@ const media = { const output = await providers.runAll({ media: media }) - -if (!output) console.log("No stream found") -console.log(`stream url: ${output.stream.playlist}`) ``` + +Now we have our stream in the output variable. (If the output is `null` then nothing could be found.) +To find out how to use the streams, check out [Using streams](../2.Essentials/4.using-streams.md). diff --git a/.docs/content/1.Get Started/3.examples.md b/.docs/content/1.Get Started/3.examples.md new file mode 100644 index 0000000..4dec826 --- /dev/null +++ b/.docs/content/1.Get Started/3.examples.md @@ -0,0 +1,5 @@ +# Examples + +- list a few examples, just link to github folders + +TODO diff --git a/.docs/content/2.Essentials/0.usage-on-x.md b/.docs/content/2.Essentials/0.usage-on-x.md index 3f66e05..9305109 100644 --- a/.docs/content/2.Essentials/0.usage-on-x.md +++ b/.docs/content/2.Essentials/0.usage-on-x.md @@ -1,6 +1,50 @@ # How to use on X -- General usage -- How to run on server? -- How to run on client? -- How to run on native app? +The library can run in many environments, so it can be tricky to figure out how to set it up. + +So here is a checklist, for more specific environments, keep reading below: + - When requests are very restricted (like browser client-side). Configure a proxied fetcher. + - When your requests come from the same device it will be streamed on (Not compatible with proxied fetcher). Set `consistentIpForRequests: true`. + - To set a target. Consult [Targets](./1.targets.md). + +To make use of the examples below, You check check out the following pages: + - [Quick start](../1.Get%20Started/1.quick-start.md) + - [Using streams](../2.Essentials/4.using-streams.md) + +## NodeJs server +```ts +import { makeProviders, makeStandardFetcher, targets } from '@movie-web/providers'; + +const providers = makeProviders({ + fetcher: makeStandardFetcher(fetch), + target: chooseYourself, // check out https://providers.docs.movie-web.app/essentials/targets +}) +``` + +## Browser client-side + +Doing client-side usage of the provider package requires a hosted version of simple-proxy. +Read more [about proxy fetchers](./2.fetchers.md#using-fetchers-on-the-browser). + +```ts +import { makeProviders, makeStandardFetcher, targets } from '@movie-web/providers'; + +const proxyUrl = "https://your.proxy.workers.dev/"; + +const providers = makeProviders({ + fetcher: makeStandardFetcher(fetch), + proxiedFetcher: makeSimpleProxyFetcher(proxyUrl, fetch), + target: target.BROWSER, +}) +``` + +## React native +```ts +import { makeProviders, makeStandardFetcher, targets } from '@movie-web/providers'; + +const providers = makeProviders({ + fetcher: makeStandardFetcher(fetch), + target: target.NATIVE, + consistentIpForRequests: true, +}) +``` diff --git a/.docs/content/2.Essentials/1.targets.md b/.docs/content/2.Essentials/1.targets.md index d59e6d8..cf1858b 100644 --- a/.docs/content/2.Essentials/1.targets.md +++ b/.docs/content/2.Essentials/1.targets.md @@ -1,13 +1,14 @@ # Targets -When making an instance of the library using `makeProviders()`. It will immediately require choosing a target. +When creating provider controls, you will immediately be required to choose a target. -::alert{type="info"} +::alert{type="warning"} A target is the device where the stream will be played on. **Where the scraping is run has nothing to do with the target**, only where the stream is finally played in the end is significant in choosing a target. :: #### Possible targets - **`targets.BROWSER`** Stream will be played in a browser with CORS -- **`targets.NATIVE`** Stream will be played natively -- **`targets.ALL`** Stream will be played on a device with no restrictions of any kind +- **`targets.BROWSER_EXTENSION`** Stream will be played in a browser using the movie-web extension (WIP) +- **`targets.NATIVE`** Stream will be played on a native video player +- **`targets.ANY`** No restrictions for selecting streams, will just give all of them diff --git a/.docs/content/2.Essentials/2.fetchers.md b/.docs/content/2.Essentials/2.fetchers.md index 7b3c0cf..78d83e7 100644 --- a/.docs/content/2.Essentials/2.fetchers.md +++ b/.docs/content/2.Essentials/2.fetchers.md @@ -1,13 +1,13 @@ # Fetchers -When making an instance of the library using `makeProviders()`. It will immediately make a fetcher. +When creating provider controls, it will need you to configure a fetcher. This comes with some considerations depending on the environment youre running. ## Using `fetch()` In most cases, you can use the `fetch()` API. This will work in newer versions of Node.js (18 and above) and on the browser. ```ts -const fetcher = makeDefaultFetcher(fetch); +const fetcher = makeStandardFetcher(fetch); ``` If you using older version of Node.js. You can use the npm package `node-fetch` to polyfill fetch: @@ -15,7 +15,7 @@ If you using older version of Node.js. You can use the npm package `node-fetch` ```ts import fetch from "node-fetch"; -const fetcher = makeDefaultFetcher(fetch); +const fetcher = makeStandardFetcher(fetch); ``` ## Using fetchers on the browser @@ -29,7 +29,7 @@ const fetcher = makeSimpleProxyFetcher("https://your.proxy.workers.dev/", fetch) If you aren't able to use this specific proxy and need to use a different one, you can make your own fetcher in the next section. -## Making a custom fetcher +## Making a derived fetcher In some rare cases, a custom fetcher will need to be made. This can be quite difficult to do from scratch so it's recommended to base it off an existing fetcher and building your own functionality around it. @@ -37,6 +37,7 @@ In some rare cases, a custom fetcher will need to be made. This can be quite dif export function makeCustomFetcher(): Fetcher { const fetcher = makeStandardFetcher(f); const customFetcher: Fetcher = (url, ops) => { + // Do something with the options and url here return fetcher(url, ops); }; @@ -44,4 +45,30 @@ export function makeCustomFetcher(): Fetcher { } ``` -If you need to make your own fetcher for a proxy. Make sure you make it compatible with the following headers: `Cookie`, `Referer`, `Origin`. Proxied fetchers need to be able to write those headers when making a request. +If you need to make your own fetcher for a proxy. Make sure you make it compatible with the following headers: `Set-Cookie`, `Cookie`, `Referer`, `Origin`. Proxied fetchers need to be able to write/read those headers when making a request. + + +## Making a fetcher from scratch + +In some even rare cases, you need to make one completely from scratch. +This is the list of features it needs: + - Send/read every header + - Parse JSON, otherwise parse as text + - Send JSON, Formdata or normal strings + - get final destination url + +It's not recommended to do this at all, but if you have to. You can base your code on the original implementation of `makeStandardFetcher`. Check the source code for it. + +Here is a basic template on how to make your own custom fetcher: + +```ts +const myFetcher: Fetcher = (url, ops) => { + // Do some fetching + return { + body: {}, + finalUrl: "", + headers: new Headers(), // should only contain headers from ops.readHeaders + statusCode: 200, + }; +} +``` diff --git a/.docs/content/2.Essentials/3.customize-providers.md b/.docs/content/2.Essentials/3.customize-providers.md index 461e575..37cfa7b 100644 --- a/.docs/content/2.Essentials/3.customize-providers.md +++ b/.docs/content/2.Essentials/3.customize-providers.md @@ -3,3 +3,5 @@ - use makeProviders() - use buildProviders() - only use some providers + +TODO diff --git a/.docs/content/2.Essentials/4.using-streams.md b/.docs/content/2.Essentials/4.using-streams.md index 6c9f645..3878587 100644 --- a/.docs/content/2.Essentials/4.using-streams.md +++ b/.docs/content/2.Essentials/4.using-streams.md @@ -2,3 +2,5 @@ - How to use the outputs - file based streams VS hls + +TODO diff --git a/.docs/content/3.In-depth/0.sources-and-embeds.md b/.docs/content/3.In-depth/0.sources-and-embeds.md index 3a0e75f..116e629 100644 --- a/.docs/content/3.In-depth/0.sources-and-embeds.md +++ b/.docs/content/3.In-depth/0.sources-and-embeds.md @@ -2,3 +2,5 @@ - How do sources and embeds differ - How do sources and embeds interact + +TODO diff --git a/.docs/content/3.In-depth/1.new-providers.md b/.docs/content/3.In-depth/1.new-providers.md index 826c13d..9d25a4b 100644 --- a/.docs/content/3.In-depth/1.new-providers.md +++ b/.docs/content/3.In-depth/1.new-providers.md @@ -3,3 +3,5 @@ - How to make new sources or embeds - Ranking - Link to flags + +TODO diff --git a/.docs/content/3.In-depth/2.flags.md b/.docs/content/3.In-depth/2.flags.md index 06c11b0..5035710 100644 --- a/.docs/content/3.In-depth/2.flags.md +++ b/.docs/content/3.In-depth/2.flags.md @@ -2,3 +2,5 @@ - what are flags? - list of all flags and their meaning + +TODO diff --git a/.docs/content/4.Extra topics/0.development.md b/.docs/content/4.Extra topics/0.development.md index 9ef4dda..e5d7ed3 100644 --- a/.docs/content/4.Extra topics/0.development.md +++ b/.docs/content/4.Extra topics/0.development.md @@ -5,3 +5,5 @@ - How to use the fetchers, when to use proxiedFetcher - How to use the context - Testing of contributions + +TODO